Introduction
The Klarna Checkout REST API is the underlying interface for all our available client libraries. This reference guide was created for those who are developing for platforms currently not supported by our client libraries, or those who are interested in diving into the details of our API.
Entry points
The Klarna Checkout API can be accessed from the following entry points, depending on the environment you are working in:
https://checkout.klarna.com/checkout/orders - For transactions in the live environment
https://checkout.testdrive.klarna.com/checkout/orders - For test transactions in Klarna’s testing environment.
HTTPS vs HTTP
To help ensure data security, only HTTPS is allowed. HTTP is not supported.
JSON, Unicode
JSON is used across all communications as the syntax of the media-types. Only JSON’s default UTF-8 encoding is supported.
Authorization
Every API request has to be authenticated by using the Authentication HTTP request header. Only a proprietary Klarna authentication scheme is supported, in the format of Klarna authorization header.
The authorization header is calculated for each request using these steps of this formula: base64(hex(sha256 (request_payload + shared_secret))), where
- request_payload is the payload of the request, or an empty string for GET requests
- shared_secret is the secret key assigned to your EID by Klarna
Authorization: Klarna pwhcueUff0MmwLShJiBE9JHA==
Order resource
Legend
O, optional
M, mandatory
R, read only
resource properties
Name | Type | Description | |
---|---|---|---|
Name id | Type string | R | Description Unique identifier of the Klarna Checkout Order |
Name purchase_country | Type string | M | Description Country in which the purchase is done (ISO-3166-alpha2) |
Name purchase_currency | Type string | M | Description Currency in which the purchase is done (ISO-4217) |
Name locale | Type string | M | Description Locale indicative for language & other location-specific details (RFC1766) |
Name status | Type string | R * | Description Status. checkout_incomplete by default, alternatively checkout_complete , created |
Name reference | Type string | R | Description End-consumer friendly reference |
Name reservation | Type string | R | Description Reservation number to be used in the XML-RPC API |
Name recurring | Type boolean | O | Description Only in Sweden, Norway and Finland: Indicates whether this purchase is a recurring order |
Name recurring_token | Type string | R | Description Token to be used when creating recurring orders |
Name merchant_reference | Type merchant reference object | O * | Description Merchant references |
Name billing_address | Type address object | R | Description The billing address |
Name shipping_address | Type address object | O | Description The shipping address |
Name cart | Type cart object | M | Description The cart |
Name customer | Type customer object | O | Description Information about the liable customer of the order. |
Name gui | Type gui object | O | Description The gui object |
Name merchant | Type merchant object | M | Description Merchant related information. |
Name attachment | Type attachment object | O | Description Additional purchase information required for some industries. |
Name external_payment_methods | Type array of external payment method objects | O | Description External payment methods |
Name external_checkouts | Type array of external checkout objects | O | Description External checkout providers |
Name options | Type options object | O | Description Options for this purchase, read more here . |
Name started_at | Type string | R | Description Timestamp of when the Checkout started (ISO-8601) |
Name completed_at | Type string | R | Description Timestamp of when the Checkout was completed (ISO-8601) |
Name created_at | Type string | R | Description Timestamp of when the Order was created (ISO-8601) |
Name last_modified_at | Type string | R | Description Timestamp of when the Checkout was last modified (ISO-8601) |
Name expires_at | Type string | R | Description Timestamp of when the Checkout will expire (ISO-8601) |
Name merchant_requested | Type object | R | Description Stores merchant requested data. e.g. the state of the optional additional_checkbox |
* When the order status is checkout_complete
or created
all properties become read only, except status
and merchant_reference
.
merchant reference object properties
Variable | Type | Description | |
---|---|---|---|
Variable orderid1 | Type string | O | Description Used for storing merchant’s internal order number or other reference. |
Variable orderid2 | Type string | O | Description Used for storing merchant’s internal order number or other reference. |
address object properties
Variable | Type | Description | |
---|---|---|---|
Variable given_name | Type string | R | Description First name |
Variable family_name | Type string | R | Description Last name |
Variable care_of | Type string | R | Description c/o |
Variable reference | Type string | O | Description Only for B2B orders. Reference information entered by the customer for this B2B order. |
Variable organization_name | Type string | R | Description Only for B2B orders. The name of the organization placing the order. |
Variable street_address | Type string | R | Description Only in Sweden, Norway and Finland: Street address (street name, street number, street extension) |
Variable street_name | Type string | R | Description Only in Germany and Austria: Street name |
Variable street_number | Type string | R | Description Only in Germany and Austria**:** Street number |
Variable postal_code | Type string | O | Description Postal code |
Variable city | Type string | R | Description City |
Variable country | Type string | R | Description Country (ISO-3166 alpha) |
Variable email | Type string | O | Description E-mail address |
Variable phone | Type string | R | Description Phone number |
Variable title | Type string | R | Description Only in Germany and Austria**:** The customer’s title, possible values are “Herr” and “Frau” |
cart object properties
Variable | Type | Description | |
---|---|---|---|
Variable total_price_excluding_tax | Type integer | R | Description Total price (excluding tax) in cents |
Variable total_tax_amount | Type integer | R | Description Total tax amount in cents |
Variable total_price_including_tax | Type integer | R | Description Total price (including tax) in cents |
Variable items | Type array of cart item objects | M | Description List of cart items |
cart item object properties
Variable | Type | Description | |
---|---|---|---|
Variable type | Type string | O | Description Type. physical by default, alternatively discount , shipping_fee |
Variable ean | Type string | O | Description The item’s International Article Number. Please note this property is currently not returned when fetching the full order resource. |
Variable reference | Type string | M | Description Reference, usually the article number |
Variable name | Type string | M | Description Name, usually a short description |
Variable uri | Type string | O | Description Item product page URI. Please note this property is currently not returned when fetching the full order resource. |
Variable image_uri | Type string | O | Description Item image URI. Please note this property is currently not returned when fetching the full order resource. |
Variable quantity | Type integer | M | Description Quantity |
Variable unit_price | Type integer | M | Description Unit price in cents, including tax |
Variable total_price_excluding_tax | Type integer | R | Description Total price (excluding tax) in cents |
Variable total_tax_amount | Type integer | R | Description Total tax amount, in cents |
Variable total_price_including_tax | Type integer | R | Description Total price (including tax) in cents |
Variable discount_rate | Type integer | O | Description Percentage of discount, multiplied by 100 and provided as an integer. i.e. 9.57% should be sent as 957 |
Variable tax_rate | Type integer | M | Description Percentage of tax rate, multiplied by 100 and provided as an integer. i.e. 13.57% should be sent as 1357 |
customer object properties
Variable | Type | Description | |
---|---|---|---|
Variable date_of_birth | Type string | O | Description If provided by customer, or retrieved from national ID. The customer’s birthdate (YYYY-MM-DD) |
Variable gender | Type string | O | Description Retrieved from national ID or billing_address.title in Germany. ‘female’ or ‘male’ |
Variable type | Type string | R | Description Type. The default supported value is ‘person’. If B2B is enabled for the e-store ID, the value may be ‘organization’. |
Variable organization_registration_id | Type string | O | Description For B2B, this field is used for the organization’s official registration id (Organization number). |
gui object properties
Note: The gui_object
cannot be changed. It can only be set in the the create operation.
Variable | Type | Description | |
---|---|---|---|
Variable layout | Type string | O | Description Layout. desktop by default, alternatively mobile |
Variable options | Type array of strings | O | Description An array of options to define the checkout behaviour. Supported options disable_autofocus . |
Variable snippet | Type string | R | Description HTML snippet |
merchant object properties
Variable | Type | Description | |
---|---|---|---|
Variable id | Type string | M | Description Unique identifier (EID) |
Variable terms_uri | Type string | M | Description URI of your terms and conditions |
Variable organization_terms_uri | Type string | O | Description URI of your terms and conditions for B2B purchases/organizations (may be used in the B2B flow) |
Variable cancellation_terms_uri | Type string | O | Description URI of the cancellation terms |
Variable checkout_uri | Type string | M | Description URI of your checkout page |
Variable confirmation_uri | Type string | M | Description URI of your confirmation page |
Variable push_uri | Type string | M | Description URI of your push-notification page |
Variable validation_uri | Type string | O | Description URI of your validation page, see validate a checkout order . |
Variable back_to_store_uri | Type string | O | Description URI of your store page. Used on the settlement page. |
attachment object properties
Variable | Type | Description | |
---|---|---|---|
Variable body | Type string | M | Description The attachment body. |
Variable content_type | Type string | M | Description The content type of the body property. |
A list of available attachment types can be found here .
external payment method object properties
Variable | Type | Description | |
---|---|---|---|
Variable name | Type string | M | Description Payment method name |
Variable redirect_uri | Type string | M | Description URI of external payment method page |
Variable image_uri | Type string | O | Description URI of external payment method image (https://) |
Variable fee | Type integer | O | Description Fee in cents, including tax |
Variable description | Type string | O | Description 500 character limit. Links can be set with the Markdown syntax Text |
external checkout object properties
Variable | Type | Description | |
---|---|---|---|
Variable name | Type string | M | Description Checkout name |
Variable redirect_uri | Type string | M | Description URI of external payment method page |
Variable image_uri | Type string | M | Description URI of external payment method image (https://) |
Variable fee | Type integer | O | Description Fee in cents, including tax |
options object properties
Variable | Type | Description | |
---|---|---|---|
Variable color_button | Type string | O | Description Only hexadecimal values are allowed. |
Variable color_button_text | Type string | O | Description Only hexadecimal values are allowed. |
Variable color_checkbox | Type string | O | Description Only hexadecimal values are allowed. |
Variable color_checkbox_checkmark | Type string | O | Description Only hexadecimal values are allowed. |
Variable color_header | Type string | O | Description Only hexadecimal values are allowed. |
Variable color_link | Type string | O | Description Only hexadecimal values are allowed. |
Variable shipping_details | Type string | O | Description Shipping information displayed on the confirmation page. Maximum 70 characters. |
Variable phone_mandatory | Type boolean | O | Description Making the phone field mandatory (Only available in Germany and Austria) |
Variable allow_separate_shipping_address | Type boolean | O | Description To allow separate shipping addresses |
Variable packstation_enabled | Type boolean | O | Description Enable packstation (Only available in Germany) |
Variable allowed_customer_types | Type list of string | O | Description List of the allowed customer types. Allowed values are ‘person’ and ‘organization’ if B2B is enabled on the e-store ID. |
Variable date_of_birth_mandatory | Type boolean | O | Description Making the date of birth mandatory |
Variable additional_checkbox | Type checkbox object | O | Description Additional merchant defined checkbox. e.g. for Newsletter opt-in. |
Variable additional_merchant_terms | Type string | O | Description Additional merchant defined field. e.g. Extra terms and conditions to show. |
checkbox object properties
Variable | Type | Description | |
---|---|---|---|
Variable text | Type string | M | Description Text that will be displayed to the consumer aside the checkbox. (max 255 characters). This text can contain links using the format Link text . |
Variable checked | Type boolean | M | Description Default state of the additional checkbox. It will use this value when loaded for the first time. |
Variable required | Type boolean | M | Description Whether it is required for the consumer to check the additional checkbox box or not in order to complete the purchase. |
merchant_requested object properties
Variable | Type | Description | |
---|---|---|---|
Variable additional_checkbox | Type boolean | R | Description Informs whether the the additional_checkbox is checked or not, when applicable. |
Errors
Klarna uses conventional HTTP response codes to indicate success or failure of an API call.
Status code | Description | |
---|---|---|
Status code 200 | OK | Description The request was successful. |
Status code 201 | Created | Description The request was successful and created a new resource at the URI described by the Content-Location response header |
Status code 400 | Bad Request | Description The request did not pass validation due to syntax or semantic errors. Error message should indicate the error. |
Status code 401 | Unauthorized | Description Authentication failed due to an invalid or missing Authentication request header. |
Status code 403 | Forbidden | Description The server refused to fulfil it. |
Status code 404 | Not Found | Description There is no resource matching the request URI. |
Status code 405 | Method Not Allowed | Description The resource did not expected the request method. |
Status code 406 | Not Acceptable | Description The server cannot fulfil the Accept request header. |
Status code 415 | Media Type Not Supported | Description The server does not support the media-type specified by the Content-Type request header. |
Versioning
The Klarna Checkout API is versioned through custom media types. When we make changes to the API which are not backwards compatible, we will increment the version number in the media type.
Current version: application/vnd.klarna.checkout.aggregated-order-v2+json
Supported locales
The locale configuration in Klarna Checkout affects the iframe language and all further communication made between Klarna and the consumer.
This table specifies the supported combinations of country, currently and locale.
Country | Language | purchase_country | purchase_currency | locale |
---|---|---|---|---|
Country Sweden | Language Swedish | purchase_country SE | purchase_currency SEK | locale sv-se |
Country Sweden | Language English | purchase_country SE | purchase_currency SEK | locale en-us |
Country Finland | Language Finnish | purchase_country FI | purchase_currency EUR | locale fi-fi |
Country Finland | Language Swedish | purchase_country FI | purchase_currency EUR | locale sv-fi |
Country Finland | Language English | purchase_country FI | purchase_currency EUR | locale en-us |
Country Norway | Language Norwegian | purchase_country NO | purchase_currency NOK | locale nb-no |
Country Norway | Language English | purchase_country NO | purchase_currency NOK | locale en-us |
Country Germany | Language German | purchase_country DE | purchase_currency EUR | locale de-de |
Country Germany | Language English | purchase_country DE | purchase_currency EUR | locale en-us |
Country Austria | Language German | purchase_country AT | purchase_currency EUR | locale de-at |
Country Austria | Language English | purchase_country AT | purchase_currency EUR | locale en-us |
Resources
Aggregated Order
Create
Overview
- Description: Create a new Checkout Order resource
- Request
- Method: POST
- URI: https://checkout.testdrive.klarna.com/checkout/orders
- Accept: application/vnd.klarna.checkout.aggregated-order-v2+json
- Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json
- Body: …
- Response
- Location: URI of the new Checkout Order resource
HTTP Request
Once the order is created, the order will contain a HTML snippet that needs to be embedded on your Checkout page.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
POST /checkout/orders HTTP/1.1 Host: checkout.testdrive.klarna.com Accept: application/vnd.klarna.checkout.aggregated-order-v2+json Authorization: Klarna pwhcueUff0MmwLShJiBE9JHA== Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json { "merchant_reference": { "orderid1": "123456789", "orderid2": "123456789" }, "purchase_country": "se", "purchase_currency": "sek", "locale": "sv-se", "cart": { "items": [ { "reference": "123456789", "name": "Klarna t-shirt", "quantity": 2, "ean": "1234567890123", "uri": "http://example.com/product.php?123456789", "image_uri": "http://example.com/product_image.php?123456789", "unit_price": 12300, "discount_rate": 1000, "tax_rate": 2500 }, { "type": "shipping_fee", "reference": "SHIPPING", "name": "Shipping fee", "quantity": 1, "unit_price": 4900, "tax_rate": 2500 } ] }, "shipping_address": { "given_name": "Testperson-se", "family_name": "Approved", "street_address": "Stårgatan 1", "postal_code": "12345", "city": "Ankeborg", "country": "se", "email": "checkout@testdrive.klarna.com", "phone": "0765260000" }, "gui": { "layout": "desktop" }, "merchant": { "id": "0", "back_to_store_uri": "http://example.com", "terms_uri": "http://example.com/terms.php", "checkout_uri": "https://example.com/checkout.php", "confirmation_uri": "https://example.com/thankyou.php?sid=123&klarna_order={checkout.order.id}", "push_uri": "https://example.com/push.php?sid=123&klarna_order={checkout.order.id}" } }
HTTP Response
1 2 3
HTTP/1.1 201 Created Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json Location: https://checkout.testdrive.klarna.com/checkout/orders/{id}
Read
Overview
- Description: Read a Checkout Order resource
- Request
- Method: GET
- URI: https://checkout.testdrive.klarna.com/checkout/orders/{id}
- Accept: application/vnd.klarna.checkout.aggregated-order-v2+json
- Content-Type: -
- Body: -
- Response
- A representation of the Checkout Order
HTTP Request
1 2 3 4
GET /checkout/orders/{id} HTTP/1.1 Host: checkout.testdrive.klarna.com Accept: application/vnd.klarna.checkout.aggregated-order-v2+json Authorization: Klarna pwhcueUff0MmwLShJiBE9JHA==
HTTP Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
HTTP/1.1 200 OK Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json { "id": "1A2B3C4D5E6F1A2B3C4D5E6F", "merchant_reference": { "orderid1": "123456789", "orderid2": "123456789" }, "purchase_country": "se", "purchase_currency": "sek", "locale": "sv-se", "status": "created", "reference": "Q1W2E3", "reservation": "123456789", "started_at": "2012-01-18T11:45:00+01:00", "completed_at": "2012-01-18T11:51:00+01:00", "created_at": "2012-01-18T11:52:00+01:00", "last_modified_at": "2012-01-18T11:52:00+01:00", "expires_at": "2012-02-01T11:52:00+01:00", "shipping_address": { "given_name": "Testperson-se", "family_name": "Approved", "care_of": "Testperson", "street_address": "Stårgatan 1", "postal_code": "12345", "city": "Ankeborg", "country": "se", "email": "checkout@testdrive.klarna.com", "phone": "0765260000" }, "billing_address": { "given_name": "Testperson-se", "family_name": "Approved", "care_of": "Testperson", "street_address": "Stårgatan 1", "postal_code": "12345", "city": "Ankeborg", "country": "se", "email": "checkout@testdrive.klarna.com", "phone": "0765260000" }, "cart": { "total_price_excluding_tax": 20280, "total_tax_amount": 6760, "total_price_including_tax": 27040, "items": [ { "reference": "123456789", "name": "Klarna t-shirt", "quantity": 2, "unit_price": 12300, "discount_rate": 1000, "tax_rate": 2500, "total_price_excluding_tax": 16605, "total_tax_amount": 5535, "total_price_including_tax": 22140, }, { "type": "shipping_fee", "reference": "SHIPPING", "name": "Shipping fee", "quantity": 1, "unit_price": 4900, "tax_rate": 2500, "total_price_excluding_tax": 3675, "total_tax_amount": 1225, "total_price_including_tax": 4900, } ] }, "customer": { "type": "person", }, "gui": { "layout": "desktop", "snippet": "..." }, "merchant": { "id": "0", "terms_uri": "http://example.com/terms.php", "checkout_uri": "https://example.com/checkout.php", "confirmation_uri": "https://example.com/thankyou.php?sid=123&klarna_order={checkout.order.id}", "push_uri": "https://example.com/push.php?sid=123&klarna_order={checkout.order.id}" } }
Update
Overview
- Description: Update a Checkout Order resource
- Request
- Method: POST
- URI: https://checkout.testdrive.klarna.com/checkout/orders/{id}
- Accept: application/vnd.klarna.checkout.aggregated-order-v2+json
- Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json
- Body: …
- Response
- An updated representation of the Checkout Order
Please note: For orders in state checkout_complete, only the merchant_reference and status properties can be updated. For orders in state created, only the merchant_reference can be updated.
HTTP Request
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58
POST /checkout/orders/{id} HTTP/1.1 Host: checkout.testdrive.klarna.com Accept: application/vnd.klarna.checkout.aggregated-order-v2+json Authorization: Klarna pwhcueUff0MmwLShJiBE9JHA== Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json { "merchant_reference": { "orderid1": "123456789", "orderid2": "123456789" }, "purchase_country": "se", "purchase_currency": "sek", "locale": "sv-se", "cart": { "items": [ { "reference": "123456789", "name": "Klarna t-shirt", "quantity": 4, "ean": "1234567890123", "uri": "http://example.com/product.php?123456789", "image_uri": "http://example.com/product_image.php?123456789", "unit_price": 12300, "discount_rate": 1000, "tax_rate": 2500 }, { "type": "shipping_fee", "reference": "SHIPPING", "name": "Shipping fee", "quantity": 1, "unit_price": 4900, "tax_rate": 2500 } ] }, "shipping_address": { "given_name": "Testperson-se", "family_name": "Approved", "street_address": "Stårgatan 1", "postal_code": "12345", "city": "Ankeborg", "country": "se", "email": "checkout@testdrive.klarna.com", "phone": "0765260000" }, "gui": { "layout": "desktop" }, "merchant": { "id": "0", "terms_uri": "http://example.com/terms.php", "checkout_uri": "https://example.com/checkout.php", "confirmation_uri": "https://example.com/thankyou.php?sid=123&klarna_order={checkout.order.id}", "push_uri": "https://example.com/push.php?sid=123&klarna_order={checkout.order.id}" } }
HTTP Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
HTTP/1.1 200 OK Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json { "id": "1A2B3C4D5E6F1A2B3C4D5E6F", "merchant_reference": { "orderid1": "123456789", "orderid2": "123456789" }, "purchase_country": "se", "purchase_currency": "sek", "locale": "sv-se", "status": "checkout_incomplete", "reference": "Q1W2E3", "reservation": "123456789", "started_at": "2012-01-18T11:45:00+01:00", "completed_at": "2012-01-18T11:51:00+01:00", "created_at": "2012-01-18T11:52:00+01:00", "last_modified_at": "2012-01-18T11:52:00+01:00", "expires_at": "2012-02-01T11:52:00+01:00", "shipping_address": { "given_name": "Testperson-se", "family_name": "Approved", "care_of": "Testperson", "street_address": "Stårgatan 1", "postal_code": "12345", "city": "Ankeborg", "country": "se", "email": "checkout@testdrive.klarna.com", "phone": "0765260000" }, "cart": { "total_price_excluding_tax": 36885, "total_tax_amount": 12295, "total_price_including_tax": 49180, "items": [ { "reference": "123456789", "name": "Klarna t-shirt", "quantity": 4, "unit_price": 12300, "discount_rate": 1000, "tax_rate": 2500, "total_price_excluding_tax": 33210, "total_tax_amount": 11070, "total_price_including_tax": 44280, }, { "type": "shipping_fee", "reference": "SHIPPING", "name": "Shipping fee", "quantity": 1, "unit_price": 4900, "tax_rate": 2500, "total_price_excluding_tax": 3675, "total_tax_amount": 1225, "total_price_including_tax": 4900, } ] }, "customer": { "type": "person", }, "gui": { "layout": "desktop", "snippet": "..." }, "merchant": { "id": "0", "terms_uri": "http://example.com/terms.php", "checkout_uri": "https://example.com/checkout.php", "confirmation_uri": "https://example.com/thankyou.php?sid=123&klarna_order={checkout.order.id}", "push_uri": "https://example.com/push.php?sid=123&klarna_order={checkout.order.id}" } }
Recurring Order
Create
Overview
- Description: Create a new Recurring Checkout Order resource. You must first have created a aggregated order with the option “recurring” set to true and then use the recurring_token returned on the resource
- Request
- Method: POST
- URI: https://checkout.testdrive.klarna.com/checkout/recurring/{recurring_token}/orders
- Accept: application/vnd.klarna.checkout.recurring-order-accepted-v1+json
- Content-Type: application/vnd.klarna.checkout.recurring-order-v1+json
- Body: …
- Response
- See examples below
HTTP Request
Set activate TRUE if the order should be auto activated. Do not send activate at all if order should not be auto activated. In this case an activation through the normal flow is needed.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
POST /checkout/recurring/\{recurring_token\}/orders HTTP/1.1 Host: checkout.testdrive.klarna.com Accept: application/vnd.klarna.checkout.recurring-order-accepted-v1+json Authorization: Klarna o4qs59NZqPKm6IDr6E/GNA== Content-Type: application/vnd.klarna.checkout.recurring-order-v1+json { "activate": true, "cart": { "items": [ { "type": "physical", "reference": "123456789", "name": "Tomatoes (Spain)", "quantity": 2, "unit_price": 950, "discount_rate": 1000, "tax_rate": 2500 }, { "type": "physical", "reference": "987654321", "name": "Rotten Tomatoes", "quantity": 2, "unit_price": -100, "discount_rate": 0, "tax_rate": 0 } ] }, "billing_address": { "given_name": "Testperson-se", "family_name": "Approved", "street_address": "Stårgatan 1", "postal_code": "12345", "city": "Ankeborg", "country": "se", "email": "checkout@testdrive.klarna.com", "phone": "0765260000" }, "shipping_address": { "given_name": "Testperson-se", "family_name": "Approved", "street_address": "Stårgatan 1", "postal_code": "12345", "city": "Ankeborg", "country": "se", "email": "checkout@testdrive.klarna.com", "phone": "0765260000" }, "purchase_currency": "sek", "purchase_country": "se", "locale": "sv-se", "merchant_reference": { "orderid1": "123", "orderid2": "345" }, "merchant": { "id": "2" } }
HTTP Response
Approved - Auto activate
1 2 3 4 5 6
HTTP/1.1 200 OK Content-Type: application/vnd.klarna.checkout.recurring-order-accepted-v1+json { "invoice": "{{_}}" }
Approved - No auto activate
1 2 3 4 5 6
HTTP/1.1 200 OK Content-Type: application/vnd.klarna.checkout.recurring-order-accepted-v1+json { "reservation": "{{_}}" }
Denied - Not accepted billing country
1 2 3 4 5 6 7 8
HTTP/1.1 403 Forbidden Content-Type: application/vnd.klarna.error-v1+json { "http_status_code": 403, "http_status_message": "Forbidden", "internal_message": "not_accepted_billing_country" }
Denied - Service unavailable
1 2 3 4 5 6 7
HTTP/1.1 503 Service Unavailable Content-Type: application/vnd.klarna.error-v1+json { "http_status_code": 503, "http_status_message": "Service Unavailable" }
Denied - Forbidden
1 2 3 4 5 6 7 8
HTTP/1.1 403 Forbidden Content-Type: application/vnd.klarna.error-v1+json { "http_status_code": 403, "http_status_message": "Forbidden", "internal_message": "forbidden_token" }
Denied - Rejected invoice
Reasons:
- address
- rejected
1 2 3 4 5 6 7 8 9
HTTP/1.1 402 Payment Required Content-Type: application/vnd.klarna.checkout.recurring-order-rejected-v1+json { "reason": "{{<rejected_rc}}", "payment_method": { "type": "invoice" } }
Denied - Credit card
Reasons:
- temporary_failure
- limit_exceeded
- card_expired
- permanent_failure
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
HTTP/1.1 402 Payment Required Content-Type: application/vnd.klarna.checkout.recurring-order-rejected-v1+json { "reason": "{{<cc_failure}}", "payment_method": { "type": "credit_card", "credit_card_data": { "number": "**** **** **** 1234", "brand": "VISA", "expiry_year": 2014, "expiry_month": 10 } } }
Recurring Status
Fetch
Overview
- Description: Fetch a recurring status resource
- Request
- Method: GET
- URI: https://checkout.testdrive.klarna.com/checkout/recurring/{recurring_token}
- Accept: application/vnd.klarna.checkout.recurring-status-v1+json
- Content-Type: -
- Body: -
- Response
- A representation of the recurring status
HTTP Request
1 2 3 4
GET /checkout/recurring/\{recurring_token\} HTTP/1.1 Host: checkout.testdrive.klarna.com Authorization: Klarna o4qs59NZqPKm6IDr6E/GNA== Accept: application/vnd.klarna.checkout.recurring-status-v1+json
HTTP Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14
HTTP/1.1 200 OK Content-Type: application/vnd.klarna.checkout.recurring-status-v1+json { "payment_method": { "type": "credit_card", "credit_card_data": { "number": "1111 22** **** 1234", "brand": "VISA", "expiry_year": 2017, "expiry_month": 8 } } }