Klarna Checkout API V3 (1.0.0)

Download OpenAPI specification:Download

The checkout API is used to create a checkout with Klarna and update the checkout order during the purchase. As soon as the purchase is completed the order should be read and handled using the Order Management API.\n\nRead more on Klarna checkout.

Create an order

To create a new order simply provide a JSON object with the applicable properties.
The location of the newly created checkout order can be found in the location header of the response.
Please note: This is the url that should be used for future interactions (read and update) with the order, i.e. do not construct the order url based on the order id.

Request
header Parameters
Klarna-Partner
string
Request Body schema: application/json
purchase_country
required
string^[A-Za-z]{2,2}$

The purchase country of the merchant's store. The format to be used is ISO 3166 alpha-2. Eg: GB, SE, DE, US, etc.

Note: purchase country and currency need to match the defined merchant configuration. For global configuration read this https://docs.klarna.com/klarna-checkout/popular-use-cases/selling-to-multiple-countries/

purchase_currency
required
string^[A-Za-z]{3,3}$

The purchase currency of the merchant's store. The format to be used is ISO 4217. Eg: USD, EUR, SEK, GBP, etc.

Note: purchase country and currency need to match the defined merchant configuration. For global configuration read this https://docs.klarna.com/klarna-checkout/popular-use-cases/selling-to-multiple-countries/

locale
required
string^[A-Za-z]{2,2}(?:-[A-Za-z]{2,2})*$

Used to define the language and region of the customer. RFC 1766 customer's locale.

status
string

The current status of the order. The status will be ‘incomplete’ until the customer has been successfully authorized.

object (address)
object (address)
order_amount
required
integer <int64> >= 0

Total amount of the order including tax and any available discounts. The value should be in non-negative minor units.

Example: 25 Euros should be 2500.

order_tax_amount
required
integer <int64> >= 0

Total tax amount of the order. The value should be in non-negative minor units.

Example: 25 Euros should be 2500.

required
Array of objects (order_line) [ 0 .. 1000 ] items

An array containing list of line items that are part of this order. Maximum of 1000 line items could be processed in a single order.

object (customer)
object (merchant_urls)
merchant_reference1
string [ 0 .. 255 ] characters

Used for storing merchant's internal order number or other reference. If set, will be shown on the confirmation page as "order number" . The value is also available in the settlement files. (max 255 characters). Example: "45aa52f387871e3a210645d4"

merchant_reference2
string [ 0 .. 255 ] characters

Used for storing merchant's internal order number or other reference. The value is available in the settlement files. (max 255 characters). Example: "45aa52f387871e3a210645d4"

object (options)
object (attachment)
Array of objects (payment_provider)

List of external payment methods that will be displayed as part of payment methods in the checkout.

Array of objects (payment_provider)

List of external checkouts that will be displayed as part of payment methods in the checkout. The image_url is required, and the image size has to be 276x48px

shipping_countries
Array of strings

List of allowed shipping countries for this order in ISO-3166 alpha-2 format.

If specified, the customer will be able to change the shipping country in the checkout and you will be notified through ‘address_update’ callback or the ‘shipping_address_change’ javascript event.

If not specified then the default value will be the purchase country.

Example: look at billing_countries example.

Array of objects (shipping_option)

A list of shipping options available for this order.

merchant_data
string [ 0 .. 6000 ] characters

Pass through field to send any information about the order to be used later for reference while retrieving the order details (max 6000 characters).

object (gui)
object (merchant_requested)
object (shipping_option)
recurring
boolean

Indicates whether this purchase will create a token that can be used by the merchant to create recurring purchases. This must be enabled for the merchant to use. Default: false

Depending on specified country, recurring could be used for the following payment methods: Pay Later, Direct Debit, Card.

billing_countries
Array of strings

List of allowed billing countries for this order. If specified, the customer will be able to change the billing country in the checkout and you will be notified through ‘country_change’ callback or the ‘billing_address_change’ javascript event. If not specified but shipping_countries is specified, will use same values as shipping_countries. If not specified and shipping_countries is not specified, then the default value will be the purchase country.

Example: ["AD", "AE", "AG", "AI", "AL", "AM", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CF", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GR", "GS", "GT", "GU", "GY", "HK", "HN", "HR", "HU", "ID", "IE", "IL", "IM", "IN", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KI", "KM", "KN", "KR", "KW", "KY", "KZ", "LA", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SR", "ST", "SV", "SX", "SZ", "TC", "TF", "TG", "TH", "TJ", "TK", "TL", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YT", "ZA", "ZM", "ZW"]"

tags
Array of strings

Extra information added to the order.

Example: ["dangerous_goods", "bulky"]

Array of objects (discount_line)

List of discounts applied to this order via the KCO discount-service

Responses
201

successful operation

400

We were unable to create an order with the provided data. Some field constraint was violated.

401

You were not authorized to execute this operation.

post/checkout/v3/orders
Request samples
application/json
{
  • "purchase_country": "US",
  • "purchase_currency": "USD",
  • "locale": "en-US",
  • "status": "CHECKOUT_INCOMPLETE",
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "order_amount": 50000,
  • "order_tax_amount": 4545,
  • "order_lines": [
    ],
  • "customer": {
    },
  • "merchant_urls": {},
  • "merchant_reference1": "45aa52f387871e3a210645d4",
  • "merchant_reference2": "45aa52f387871e3a210645d4",
  • "options": {
    },
  • "attachment": {
    },
  • "external_payment_methods": [],
  • "external_checkouts": [],
  • "shipping_countries": [
    ],
  • "shipping_options": [
    ],
  • "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
  • "gui": {
    },
  • "merchant_requested": { },
  • "selected_shipping_option": {
    },
  • "recurring": true,
  • "billing_countries": [
    ],
  • "tags": [
    ],
  • "discount_lines": [
    ]
}
Response samples
application/json
{
  • "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
  • "name": "Women's Fashion",
  • "purchase_country": "US",
  • "purchase_currency": "USD",
  • "locale": "en-US",
  • "status": "CHECKOUT_INCOMPLETE",
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "order_amount": 50000,
  • "order_tax_amount": 4545,
  • "order_lines": [
    ],
  • "customer": {
    },
  • "merchant_urls": {},
  • "html_snippet": "<div id='klarna-checkout-container'><script>alert('Initializing Klarna Checkout');</script></div>",
  • "merchant_reference1": "45aa52f387871e3a210645d4",
  • "merchant_reference2": "45aa52f387871e3a210645d4",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "last_modified_at": "2019-08-24T14:15:22Z",
  • "options": {
    },
  • "attachment": {
    },
  • "external_payment_methods": [],
  • "external_checkouts": [],
  • "shipping_countries": [
    ],
  • "shipping_options": [
    ],
  • "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
  • "gui": {
    },
  • "merchant_requested": {
    },
  • "selected_shipping_option": {
    },
  • "recurring": true,
  • "recurring_token": "string",
  • "recurring_description": "string",
  • "billing_countries": [
    ],
  • "tags": [
    ],
  • "discount_lines": [
    ]
}

Update an order

To update an order simply provide a JSON object with the properties you want to update. Properties not provided in the request will stay the same.
Please note: an order can only be updated when the status is checkout_incomplete

Request
path Parameters
order_id
required
string
Request Body schema: application/json
purchase_country
required
string^[A-Za-z]{2,2}$

The purchase country of the merchant's store. The format to be used is ISO 3166 alpha-2. Eg: GB, SE, DE, US, etc.

Note: purchase country and currency need to match the defined merchant configuration. For global configuration read this https://docs.klarna.com/klarna-checkout/popular-use-cases/selling-to-multiple-countries/

purchase_currency
required
string^[A-Za-z]{3,3}$

The purchase currency of the merchant's store. The format to be used is ISO 4217. Eg: USD, EUR, SEK, GBP, etc.

Note: purchase country and currency need to match the defined merchant configuration. For global configuration read this https://docs.klarna.com/klarna-checkout/popular-use-cases/selling-to-multiple-countries/

locale
required
string^[A-Za-z]{2,2}(?:-[A-Za-z]{2,2})*$

Used to define the language and region of the customer. RFC 1766 customer's locale.

status
string

The current status of the order. The status will be ‘incomplete’ until the customer has been successfully authorized.

object (address)
object (address)
order_amount
required
integer <int64> >= 0

Total amount of the order including tax and any available discounts. The value should be in non-negative minor units.

Example: 25 Euros should be 2500.

order_tax_amount
required
integer <int64> >= 0

Total tax amount of the order. The value should be in non-negative minor units.

Example: 25 Euros should be 2500.

required
Array of objects (order_line) [ 0 .. 1000 ] items

An array containing list of line items that are part of this order. Maximum of 1000 line items could be processed in a single order.

object (customer)
object (merchant_urls)
merchant_reference1
string [ 0 .. 255 ] characters

Used for storing merchant's internal order number or other reference. If set, will be shown on the confirmation page as "order number" . The value is also available in the settlement files. (max 255 characters). Example: "45aa52f387871e3a210645d4"

merchant_reference2
string [ 0 .. 255 ] characters

Used for storing merchant's internal order number or other reference. The value is available in the settlement files. (max 255 characters). Example: "45aa52f387871e3a210645d4"

object (options)
object (attachment)
Array of objects (payment_provider)

List of external payment methods that will be displayed as part of payment methods in the checkout.

Array of objects (payment_provider)

List of external checkouts that will be displayed as part of payment methods in the checkout. The image_url is required, and the image size has to be 276x48px

shipping_countries
Array of strings

List of allowed shipping countries for this order in ISO-3166 alpha-2 format.

If specified, the customer will be able to change the shipping country in the checkout and you will be notified through ‘address_update’ callback or the ‘shipping_address_change’ javascript event.

If not specified then the default value will be the purchase country.

Example: look at billing_countries example.

Array of objects (shipping_option)

A list of shipping options available for this order.

merchant_data
string [ 0 .. 6000 ] characters

Pass through field to send any information about the order to be used later for reference while retrieving the order details (max 6000 characters).

object (gui)
object (merchant_requested)
object (shipping_option)
recurring
boolean

Indicates whether this purchase will create a token that can be used by the merchant to create recurring purchases. This must be enabled for the merchant to use. Default: false

Depending on specified country, recurring could be used for the following payment methods: Pay Later, Direct Debit, Card.

billing_countries
Array of strings

List of allowed billing countries for this order. If specified, the customer will be able to change the billing country in the checkout and you will be notified through ‘country_change’ callback or the ‘billing_address_change’ javascript event. If not specified but shipping_countries is specified, will use same values as shipping_countries. If not specified and shipping_countries is not specified, then the default value will be the purchase country.

Example: ["AD", "AE", "AG", "AI", "AL", "AM", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CF", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GR", "GS", "GT", "GU", "GY", "HK", "HN", "HR", "HU", "ID", "IE", "IL", "IM", "IN", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KI", "KM", "KN", "KR", "KW", "KY", "KZ", "LA", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SR", "ST", "SV", "SX", "SZ", "TC", "TF", "TG", "TH", "TJ", "TK", "TL", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YT", "ZA", "ZM", "ZW"]"

tags
Array of strings

Extra information added to the order.

Example: ["dangerous_goods", "bulky"]

Array of objects (discount_line)

List of discounts applied to this order via the KCO discount-service

Responses
200

successful operation

400

We were unable to update an order with the provided data. Some field constraint was violated.

401

You were not authorized to execute this operation.

403

You tried to modify a read only resource.

404

We did not find any order with given ID. You need to create a new order.

post/checkout/v3/orders/{order_id}
Request samples
application/json
{
  • "purchase_country": "US",
  • "purchase_currency": "USD",
  • "locale": "en-US",
  • "status": "CHECKOUT_INCOMPLETE",
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "order_amount": 50000,
  • "order_tax_amount": 4545,
  • "order_lines": [
    ],
  • "customer": {
    },
  • "merchant_urls": {},
  • "merchant_reference1": "45aa52f387871e3a210645d4",
  • "merchant_reference2": "45aa52f387871e3a210645d4",
  • "options": {
    },
  • "attachment": {
    },
  • "external_payment_methods": [],
  • "external_checkouts": [],
  • "shipping_countries": [
    ],
  • "shipping_options": [
    ],
  • "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
  • "gui": {
    },
  • "merchant_requested": { },
  • "selected_shipping_option": {
    },
  • "recurring": true,
  • "billing_countries": [
    ],
  • "tags": [
    ],
  • "discount_lines": [
    ]
}
Response samples
application/json
{
  • "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
  • "name": "Women's Fashion",
  • "purchase_country": "US",
  • "purchase_currency": "USD",
  • "locale": "en-US",
  • "status": "CHECKOUT_INCOMPLETE",
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "order_amount": 50000,
  • "order_tax_amount": 4545,
  • "order_lines": [
    ],
  • "customer": {
    },
  • "merchant_urls": {},
  • "html_snippet": "<div id='klarna-checkout-container'><script>alert('Initializing Klarna Checkout');</script></div>",
  • "merchant_reference1": "45aa52f387871e3a210645d4",
  • "merchant_reference2": "45aa52f387871e3a210645d4",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "last_modified_at": "2019-08-24T14:15:22Z",
  • "options": {
    },
  • "attachment": {
    },
  • "external_payment_methods": [],
  • "external_checkouts": [],
  • "shipping_countries": [
    ],
  • "shipping_options": [
    ],
  • "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
  • "gui": {
    },
  • "merchant_requested": {
    },
  • "selected_shipping_option": {
    },
  • "recurring": true,
  • "recurring_token": "string",
  • "recurring_description": "string",
  • "billing_countries": [
    ],
  • "tags": [
    ],
  • "discount_lines": [
    ]
}

Get order details

Get the full details of a Klarna checkout order.

Request
path Parameters
order_id
required
string
Responses
200

successful operation

401

You were not authorized to execute this operation.

403

Merchant was not activated.

404

We did not find any order with given ID. You need to create a new order.

get/checkout/v3/orders/{order_id}
Request samples
curl -i -X GET \
  'https://api.klarna.com/checkout/v3/orders/{order_id}'
Response samples
application/json
{
  • "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
  • "name": "Women's Fashion",
  • "purchase_country": "US",
  • "purchase_currency": "USD",
  • "locale": "en-US",
  • "status": "CHECKOUT_INCOMPLETE",
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "order_amount": 50000,
  • "order_tax_amount": 4545,
  • "order_lines": [
    ],
  • "customer": {
    },
  • "merchant_urls": {},
  • "html_snippet": "<div id='klarna-checkout-container'><script>alert('Initializing Klarna Checkout');</script></div>",
  • "merchant_reference1": "45aa52f387871e3a210645d4",
  • "merchant_reference2": "45aa52f387871e3a210645d4",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "last_modified_at": "2019-08-24T14:15:22Z",
  • "options": {
    },
  • "attachment": {
    },
  • "external_payment_methods": [],
  • "external_checkouts": [],
  • "shipping_countries": [
    ],
  • "shipping_options": [
    ],
  • "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
  • "gui": {
    },
  • "merchant_requested": {
    },
  • "selected_shipping_option": {
    },
  • "recurring": true,
  • "recurring_token": "string",
  • "recurring_description": "string",
  • "billing_countries": [
    ],
  • "tags": [
    ],
  • "discount_lines": [
    ]
}

Abort an order

Mark an order as aborted.

Request
path Parameters
order_id
required
string
Responses
200

successful operation

403

You tried to modify a read only resource.

404

We did not find any order with given ID. You need to create a new order.

post/checkout/v3/orders/{order_id}/abort
Request samples
curl -i -X POST \
  'https://api.klarna.com/checkout/v3/orders/{order_id}/abort'
Cookies
Terms of Service
© Klarna 2024