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
- Quote (your server). Price the cart for the buyer's country and show the total.
- Create the checkout (your server). When the buyer chooses to pay, send the cart, their email, and
KLARNA/KLARNA_PRIVATE. Keep thecheckoutIdon your server. - Authorise (the buyer's browser). Load Klarna Payments with the
clientTokenand let the buyer approve. - Confirm and poll (your server). Call confirm until it answers
COMPLETEDorFAILED.
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.
| Field | Type | Description |
|---|---|---|
items | array | At least one item, each with sku and purchaseOptionId |
country | string | Two capital letters, such as SE. Decides the market, price, and VAT |
discountCode | string | (Optional) An invalid code is not an error. It comes back in appliedDiscounts with status UNAPPLICABLE |
vatNumber | string | (Optional) Marks the buyer as a business. The country of the VAT number can outrank country and move the market and the price |
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"
}'{
"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.
| Field | Type | Description |
|---|---|---|
items | array | At least one item, each with sku and purchaseOptionId |
country | string | Two capital letters. Decides the market, price, and VAT |
email | string | The buyer's email. Sesamy trusts it as given, identifies the buyer by it, and sends the order confirmation to it |
provider | string | KLARNA |
method | string | KLARNA_PRIVATE |
discountCode | string | (Optional) Same as in the quote |
vatNumber | string | (Optional) Same as in the quote |
partnerCustomerId | string | (Optional) Your own id for the buyer, stored on the contract |
userCountry | string | (Optional) Two capital letters. The buyer's country if it differs from the cart country |
userDetails | object | (Optional) The buyer's details: isBusiness (required inside the object), names, address, businessDetails, and more |
trackingData | object | (Optional) The purchase's UTM tags. See Tracking Data |
itemSrc | string | (Optional) The page the buyer bought from. See Order Email and Source Page |
redirectUrl | string | (Optional) Where the button in the order confirmation email links to |
redirectLabel | string | (Optional) The text on that button |
language | string | (Optional) The language of the order confirmation email |
customerIp | string | (Optional) The buyer's IP address. See Buyer's IP Address |
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" }
}'{
"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: anhttp(s)URL of at most 2048 characters. Sesamy keeps the site and path and drops the query and fragment.redirectUrl: anhttpsURL 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 ofcs,da,en,fi,it,nb,pl, orsv. 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.
{
"checkoutId": "3f9c2a1e-7b44-4d0a-9e51-2c8d6a5b1f10",
"status": "COMPLETED",
"contractId": "CH-3f9c2a1e-7b44-4d0a-9e51-2c8d6a5b1f10"
}| Status | Meaning | What to do |
|---|---|---|
COMPLETED | Paid. The contract is active and contractId is included | Stop polling and show the success page |
WAITING | Klarna has not finished | Call again after 3 to 5 seconds. Stop after about a minute |
FAILED | The payment failed, and this is final for the checkout | Stop 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.
{ "code": "ALREADY_OWNED", "message": "The customer already owns this product" }| HTTP | Code | Meaning | Retry |
|---|---|---|---|
| 400 | VALIDATION | Malformed body, a missing, invalid, or unknown field, or an item you do not sell | No |
| 400 | METHOD_NOT_ALLOWED | The provider and method are not allowed or not enabled for your account | No |
| 401 | UNAUTHORIZED | The token is missing, invalid, or expired | Once, with a new token |
| 403 | FORBIDDEN | The token lacks checkout:partner | No |
| 404 | NOT_FOUND | The checkout does not exist or belongs to another vendor | No |
| 409 | ALREADY_OWNED | The buyer already owns the product. Create checkout only | No |
| 409 | NOT_PREPARED | Confirm on a checkout with no payment session | After prepare |
| 409 | ALREADY_COMPLETED | Prepare on a completed checkout | No, call confirm |
| 409 | PAYMENT_CANCELED | The buyer cancelled at Klarna | After a new prepare |
| 409 | PAYMENT_DECLINED | Klarna declined the payment | After a new prepare |
| 410 | EXPIRED | The checkout is more than 24 hours old | No, create a new one |
| 429 | RATE_LIMITED | More than 600 requests a minute for your client | After Retry-After |
| 500 | INTERNAL | An unexpected error at Sesamy | With backoff |
| 502 | PROVIDER_ERROR | Klarna could not be reached or gave an unexpected answer | With 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
- Listing Checkouts - Find and read checkouts through the Management API
- Handling Webhooks - Get notified when a checkout is confirmed or a contract is purchased
- Error Handling - How the Management API reports errors
- OAuth 2.0 - Fetch tokens with client credentials