Skip to content

Partner Checkout ​

Sell Sesamy products on your own pages, with the buyer paying in Klarna's widget and never leaving your site.

Overview ​

The Partner Checkout API is a server-to-server API. Your backend prices a cart, creates a checkout for the buyer, and hands the browser a Klarna client token. The buyer authorises in Klarna's widget, and Sesamy completes the purchase and grants access.

There are four calls:

  • Quote prices a cart and creates nothing.
  • Create checkout creates the checkout and returns the price that will be charged and a Klarna client token.
  • Prepare gives you a new client token for an existing checkout.
  • Confirm asks Sesamy to verify the payment and complete the purchase.

Sesamy charges the price it calculated when the checkout was created. Your requests never carry an amount. Klarna (KLARNA / KLARNA_PRIVATE) is the only payment method.

Base URL ​

Base URL: https://api.sesamy.com/checkout/partner/v1

The Partner Checkout API is served by the checkout service, not by api2. You read a finished checkout back through the Management API on api2, as described in Reading a Checkout.

Authentication ​

Fetch a token with the OAuth 2.0 client credentials grant, using the client id and secret Sesamy gives you. The token carries the checkout:partner permission, and Sesamy takes your vendor from it, so requests never include a vendor id. See OAuth 2.0.

Send Authorization: Bearer $ACCESS_TOKEN and Content-Type: application/json on every call. Reuse the token until it expires, and fetch a new one after a 401.

A request with a field the API does not know gets 400 VALIDATION.

The Purchase Flow ​

  1. Quote (your server). Price the cart for the buyer's country and show the total.
  2. Create the checkout (your server). When the buyer chooses to pay, send the cart, their email, and KLARNA / KLARNA_PRIVATE. Keep the checkoutId on your server.
  3. Authorise (the buyer's browser). Load Klarna Payments with the clientToken and let the buyer approve.
  4. Confirm and poll (your server). Call confirm until it answers COMPLETED or FAILED.

If the buyer cancels, Klarna declines, or the Klarna session times out, call prepare on the same checkout for a new clientToken and go back to step 3.

Endpoints ​

Quote ​

POST /quotes

Prices a cart for a country. Success is 200 OK. Nothing is created, and Sesamy caches the answer for about 60 seconds, so you can call it on product pages.

FieldTypeDescription
itemsarrayAt least one item, each with sku and purchaseOptionId
countrystringTwo capital letters, such as SE. Decides the market, price, and VAT
discountCodestring(Optional) An invalid code is not an error. It comes back in appliedDiscounts with status UNAPPLICABLE
vatNumberstring(Optional) Marks the buyer as a business. The country of the VAT number can outrank country and move the market and the price
bash
curl -s -X POST "https://api.sesamy.com/checkout/partner/v1/quotes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "sku": "sid:acme-plus-yearly", "purchaseOptionId": "yearly" }],
    "country": "SE",
    "discountCode": "WELCOME20"
  }'
json
{
  "currency": "SEK",
  "autoRenew": false,
  "items": [
    {
      "sku": "sid:acme-plus-yearly",
      "purchaseOptionId": "yearly",
      "title": "ACME Plus",
      "price": { "total": 99900, "vat": 6641, "discount": 0 }
    }
  ],
  "price": { "total": 99900, "vat": 6641, "discount": 0 },
  "appliedDiscounts": [{ "code": "WELCOME20", "status": "UNAPPLICABLE" }],
  "availablePaymentMethods": [{ "provider": "KLARNA", "method": "KLARNA_PRIVATE" }]
}

Amounts are in minor units, so 99900 is 999.00 SEK. autoRenew is read-only and comes from the product's configuration. If it is true, show the renewal terms before payment.

The quote is indicative

The price from create checkout is the one that is charged. Compare price.total and currency with what you showed before you open Klarna, and get a fresh yes from the buyer if they changed.

Create Checkout ​

POST /checkouts

Creates the checkout, prices it, attaches the buyer, and opens a Klarna session. Success is 201 Created.

Not idempotent

Every call creates a new checkout. Store the checkoutId and call it once per intended purchase. To get a new client token for the same checkout, use prepare.

FieldTypeDescription
itemsarrayAt least one item, each with sku and purchaseOptionId
countrystringTwo capital letters. Decides the market, price, and VAT
emailstringThe buyer's email. Sesamy trusts it as given, identifies the buyer by it, and sends the order confirmation to it
providerstringKLARNA
methodstringKLARNA_PRIVATE
discountCodestring(Optional) Same as in the quote
vatNumberstring(Optional) Same as in the quote
partnerCustomerIdstring(Optional) Your own id for the buyer, stored on the contract
userCountrystring(Optional) Two capital letters. The buyer's country if it differs from the cart country
userDetailsobject(Optional) The buyer's details: isBusiness (required inside the object), names, address, businessDetails, and more
trackingDataobject(Optional) The purchase's UTM tags. See Tracking Data
itemSrcstring(Optional) The page the buyer bought from. See Order Email and Source Page
redirectUrlstring(Optional) Where the button in the order confirmation email links to
redirectLabelstring(Optional) The text on that button
languagestring(Optional) The language of the order confirmation email
customerIpstring(Optional) The buyer's IP address. See Buyer's IP Address
bash
curl -s -X POST "https://api.sesamy.com/checkout/partner/v1/checkouts" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "sku": "sid:acme-plus-yearly", "purchaseOptionId": "yearly" }],
    "country": "SE",
    "email": "jane.doe@acme.example",
    "partnerCustomerId": "cust_10442",
    "provider": "KLARNA",
    "method": "KLARNA_PRIVATE",
    "trackingData": { "utmSource": "newsletter", "utmMedium": "email" }
  }'
json
{
  "checkoutId": "3f9c2a1e-7b44-4d0a-9e51-2c8d6a5b1f10",
  "status": "PENDING",
  "currency": "SEK",
  "autoRenew": false,
  "items": [
    {
      "sku": "sid:acme-plus-yearly",
      "purchaseOptionId": "yearly",
      "title": "ACME Plus",
      "price": { "total": 99900, "vat": 6641, "discount": 0 }
    }
  ],
  "price": { "total": 99900, "vat": 6641, "discount": 0 },
  "appliedDiscounts": [],
  "payment": {
    "provider": "KLARNA",
    "method": "KLARNA_PRIVATE",
    "clientData": {
      "clientToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjgyMzA1...",
      "sessionId": "b1f5a9c2-0e34-4c1d-8a7b-5d2e6f9a1c33",
      "paymentMethodCategories": [{ "identifier": "pay_over_time", "name": "Pay over time" }]
    }
  }
}

Pass the clientToken and one category identifier to Klarna Payments in the browser. A checkout lives 24 hours from this call.

Keep the checkout id on your server

Anyone with a checkout id can read the buyer's details from Sesamy's public checkout endpoints. Keep it out of URLs, browser storage, and logs the buyer can reach. Hand the browser only the clientToken.

Tracking Data ​

Send the purchase's UTM tags in trackingData: utmSource, utmMedium, utmCampaign, utmTerm, and utmContent, each a string of at most 255 characters. Sesamy stores them like the utm_* parameters on a hosted checkout link, so the purchase shows up in the same reports and on the contract. They never change the price, and the quote does not take them.

Order Email and Source Page ​

  • itemSrc: an http(s) URL of at most 2048 characters. Sesamy keeps the site and path and drops the query and fragment.
  • redirectUrl: an https URL of at most 2048 characters on your own domain or a subdomain of it, without credentials or a port.
  • redirectLabel: at most 100 characters.
  • language: one of cs, da, en, fi, it, nb, pl, or sv. Without it, the email uses your account's language, then the language of the checkout country, then English.

A value that breaks these rules gets 400 VALIDATION, and no checkout is created.

Buyer's IP Address ​

Your server makes the call to Sesamy, so Sesamy never sees the buyer's IP address unless you send it. If your site has it, send it in customerIp. Sesamy looks up the location of the address, as it does for a buyer on Sesamy's own checkout, and stores it on the checkout.

Send an IPv4 address such as 203.0.113.42 or an IPv6 address such as 2001:db8::42, at most 45 characters, without a port or network mask. Any other value gets 400 VALIDATION, and no checkout is created.

The location never changes the price. country decides the market, price, and VAT, even when the IP address points to another country. The quote does not take customerIp.

The IP address is personal data. Sesamy stores it on the checkout together with the location and does not write it to logs. Send it only if your privacy notice covers sharing it with Sesamy.

Prepare ​

POST /checkouts/{checkoutId}/prepare

Opens a new Klarna session on an existing checkout and returns a new clientToken. Success is 200 OK. Send { "provider": "KLARNA", "method": "KLARNA_PRIVATE" }. The response has the same checkoutId, price, currency, and payment fields as create checkout.

Use the token from the latest response. Prepare does not change the cart or the buyer. On a completed checkout it answers 409 ALREADY_COMPLETED.

Confirm ​

POST /checkouts/{checkoutId}/confirm

Asks Sesamy to check the payment with Klarna and complete the purchase. No request body. Success is 200 OK, and calling it again is safe.

json
{
  "checkoutId": "3f9c2a1e-7b44-4d0a-9e51-2c8d6a5b1f10",
  "status": "COMPLETED",
  "contractId": "CH-3f9c2a1e-7b44-4d0a-9e51-2c8d6a5b1f10"
}
StatusMeaningWhat to do
COMPLETEDPaid. The contract is active and contractId is includedStop polling and show the success page
WAITINGKlarna has not finishedCall again after 3 to 5 seconds. Stop after about a minute
FAILEDThe payment failed, and this is final for the checkoutStop polling. Start a new checkout if the buyer wants to retry

Klarna also notifies Sesamy directly, so a purchase can complete without your confirm call. Treat COMPLETED as the only signal that the purchase is done.

Reading a Checkout ​

Read a partner checkout back with the Management API, for example to hydrate a checkout.1#confirm webhook event or to read the attribution the purchase carried:

GET https://api2.sesamy.com/management/checkouts/{id}

The request needs the checkouts:read scope and returns checkouts of your own vendor only. A checkout older than 7 days can return 404. See Listing Checkouts.

When the purchase completes, the contractId in contract.1#purchased is CH-<checkoutId>, as for hosted checkouts. Read it from the event rather than building it yourself.

Errors ​

Every error has the same body. Branch on code. message is for logs and can change.

json
{ "code": "ALREADY_OWNED", "message": "The customer already owns this product" }
HTTPCodeMeaningRetry
400VALIDATIONMalformed body, a missing, invalid, or unknown field, or an item you do not sellNo
400METHOD_NOT_ALLOWEDThe provider and method are not allowed or not enabled for your accountNo
401UNAUTHORIZEDThe token is missing, invalid, or expiredOnce, with a new token
403FORBIDDENThe token lacks checkout:partnerNo
404NOT_FOUNDThe checkout does not exist or belongs to another vendorNo
409ALREADY_OWNEDThe buyer already owns the product. Create checkout onlyNo
409NOT_PREPAREDConfirm on a checkout with no payment sessionAfter prepare
409ALREADY_COMPLETEDPrepare on a completed checkoutNo, call confirm
409PAYMENT_CANCELEDThe buyer cancelled at KlarnaAfter a new prepare
409PAYMENT_DECLINEDKlarna declined the paymentAfter a new prepare
410EXPIREDThe checkout is more than 24 hours oldNo, create a new one
429RATE_LIMITEDMore than 600 requests a minute for your clientAfter Retry-After
500INTERNALAn unexpected error at SesamyWith backoff
502PROVIDER_ERRORKlarna could not be reached or gave an unexpected answerWith backoff

Retrying create checkout

A retry of create checkout after a 500 or 502 creates another checkout. Retry quote, prepare, and confirm freely.

Good to Know ​

  • Refunds and cancellations go through Sesamy. Do not refund in the Klarna portal, or Sesamy's records will no longer match Klarna's.
  • The buyer's email is trusted as you send it. Send the email of the person who is actually buying.

Next Steps ​

Released under the MIT License.