Klarna Payments API
Create and authorize Klarna payment sessions; create orders against authorizations.
OpenAPI Specification
openapi: 3.0.0
info:
description: >-
The payments API is used to create a session to offer Klarna's payment
methods as part of your checkout. As soon as the purchase is completed the
order should be read and handled using the [`Order Management
API`](https://docs.klarna.com/api/ordermanagement).
version: 1.0.0
title: Klarna Payments API V1
paths:
/payments/v1/sessions:
post:
summary: Create a session
description: >-
Use this API call to create a Klarna Payments session.<br/>When a
session is created you will receive the available
`payment_method_categories` for the session, a `session_id` and a
`client_token`. The `session_id` can be used to read or update the
session using the REST API. The `client_token` should be passed to the
browser.
Read more on **[Create a new payment
session](https://docs.klarna.com/klarna-payments/integrate-with-klarna-payments/step-1-initiate-a-payment/)**.
operationId: createCreditSession
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/session_create'
description: session_request
required: true
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/merchant_session'
'400':
description: >-
We were unable to create a session with the provided data. Some
field constraint was violated.
'403':
description: You were not authorized to execute this operation.
/payments/v1/sessions/{session_id}:
post:
summary: Update a session
description: >-
Use this API call to update a Klarna Payments session with new details,
in case something in the order has changed and the checkout has been
reloaded. Including if the consumer adds a new item to the cart or if
consumer details are updated.
Read more on **[Update an existing payment
session](https://docs.klarna.com/klarna-payments/other-actions/update-the-cart/)**.
operationId: updateCreditSession
parameters:
- name: session_id
in: path
description: session_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/session'
description: session_request
required: true
responses:
'204':
description: The session was updated successfully.
'400':
description: >-
We were unable to update the session with the provided data. Some
field constraint was violated.
'403':
description: You were not authorized to execute this operation.
'404':
description: The session does not exist.
get:
summary: Get details about a session
description: >-
Use this API call to get a Klarna Payments session. You can read the
Klarna Payments session at any time after it has been created, to get
information about it. This will return all data that has been collected
during the session.
Read more on **[Read an existing payment
session](https://docs.klarna.com/klarna-payments/other-actions/check-the-details-of-a-payment-session/)**.
operationId: readCreditSession
parameters:
- name: session_id
in: path
description: session_id
required: true
schema:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/session_read'
'403':
description: You were not authorized to execute this operation.
'404':
description: The session does not exist.
/payments/v1/authorizations/{authorizationToken}:
delete:
summary: Cancel an authorization
description: >-
Use this API call to cancel/release an authorization. If the
`authorization_token` received during a Klarna Payments wont be used to
place an order immediately you could release the authorization.
Read more on **[Cancel an existing
authorization](https://docs.klarna.com/klarna-payments/other-actions/cancel-an-authorization/)**.
operationId: cancelAuthorization
parameters:
- name: authorizationToken
in: path
required: true
schema:
type: string
responses:
'204':
description: The authorization was cancelled successfully.
'403':
description: You were not authorized to execute this operation.
'404':
description: The authorization does not exist.
/payments/v1/authorizations/{authorizationToken}/order:
post:
summary: Create an order
description: >-
Use this API call to create a new order. Placing an order towards Klarna
means that the Klarna Payments session will be closed and that an order
will be created in Klarna's system.<br/>When you have received the
`authorization_token` for a successful authorization you can place the
order. Among the other order details in this request, you include a URL
to the confirmation page for the customer.<br/>When the Order has been
successfully placed at Klarna, you need to handle it either through the
Merchant Portal or using [Klarnas Order Management
API](#order-management-api).
Read more on **[Create a new
order](https://docs.klarna.com/klarna-payments/integrate-with-klarna-payments/step-3-create-an-order/)**.
operationId: createOrder
parameters:
- name: authorizationToken
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create_order_request'
responses:
'200':
description: Order was successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/order'
'400':
description: >-
We were unable to create an order with the provided data. Some field
constraint was violated.
'403':
description: You were not authorized to execute this operation.
'404':
description: The authorization does not exist.
'409':
description: >-
The data in the request does not match the session for the
authorization.
/payments/v1/authorizations/{authorizationToken}/customer-token:
post:
summary: Generate a customer token
description: >-
Use this API call to create a Klarna Customer Token.<br/>After having
obtained an `authorization_token` for a successful authorization, this
can be used to create a purchase token instead of placing the order.
Creating a Klarna Customer Token results in Klarna storing customer and
payment method details.
Read more on **[Generate a costumer
token](https://docs.klarna.com/klarna-payments/in-depth-knowledge/customer-token/)**.
operationId: purchaseToken
parameters:
- name: authorizationToken
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/customer_token_creation_request'
responses:
'200':
description: Token was successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/customer_token_creation_response'
'400':
description: >-
We were unable to create a customer token with the provided data.
Some field constraint was violated.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorV2'
'403':
description: You were not authorized to execute this operation.
'404':
description: The authorization does not exist.
'409':
description: >-
The data in the request does not match the session for the
authorization.
servers:
- url: https://api.klarna.com
components:
schemas:
ErrorV2:
type: object
properties:
correlation_id:
type: string
error_code:
type: string
error_messages:
type: array
items:
type: string
address:
type: object
properties:
attention:
type: string
example: Attn
description: Attn. (if applicable). Only applicable for B2B customers.
minLength: 0
maxLength: 99
city:
type: string
example: London
description: Customers city.
minLength: 0
maxLength: 99
country:
type: string
example: GB
description: >-
Customers country. This value overrides the purchase country if
they are different. Should follow the standard of ISO 3166 alpha-2.
E.g. GB, US, DE, SE.
pattern: ^[A-Za-z]{2,2}$
email:
type: string
example: [email protected]
description: Customers email address.
minLength: 0
maxLength: 99
family_name:
type: string
example: Andersson
description: >-
Customers family name in UTF-8 encoding.
Cannot be only numbers, must be more than 1 character.
Allowed special characters: -'.
More information can be found [in this
link](https://docs.klarna.com/klarna-payments/in-depth-knowledge/customer-data-requirements/#details-needed-per-market)
minLength: 0
maxLength: 99
given_name:
type: string
example: Adam
description: >-
Customers given name in UTF-8 encoding.
Cannot be only numbers, must be more than 1 character.
Allowed special characters: -'.
More information can be found [in this
link](https://docs.klarna.com/klarna-payments/in-depth-knowledge/customer-data-requirements/#details-needed-per-market)
minLength: 0
maxLength: 99
organization_name:
type: string
description: >-
Organization name (if applicable). Only applicable for B2B
customers.
minLength: 0
maxLength: 99
phone:
type: string
example: '+44795465131'
description: Phone number. Preferably a mobile phone number.
minLength: 0
maxLength: 99
postal_code:
type: string
example: W1G 0PW
description: >-
Customers postal code. Validation according to [Universal Postal
Union addressing
system](https://www.upu.int/en/activities/addressing/postal-addressing-systems-in-member-countries.html).
E.g. 12345, W1G OPW.
minLength: 0
maxLength: 10
region:
type: string
example: OH
description: >-
Customers region or state - Mandatory for US and AU market.
Validations according to ISO 3166-2 format, e.g. OH, NJ, etc.
minLength: 0
maxLength: 99
street_address:
type: string
example: 33 Cavendish Square
description: >-
Customers street address. Validation according to [Universal Postal
Union addressing
system](https://www.upu.int/en/activities/addressing/postal-addressing-systems-in-member-countries.html).
Regional formatting is required, as follows:
UK/US/FR: 33 Cavendish Square
Rest of EU: De Ruijterkade 7
minLength: 0
maxLength: 99
street_address2:
type: string
example: Floor 22 / Flat 2
description: 'Customers street address. Second Line. '
minLength: 0
maxLength: 99
title:
type: string
example: Mr.
description: |-
Customers Title. Allowed values per country:
UK - "Mr", "Ms"
DE - "Herr", "Frau"
AT: "Herr, "Frau"
CH: de-CH: "Herr, "Frau" it-CH: "Sig.", "Sig.ra" fr-CH: "M", "Mme"
BE: "Dhr.", "Mevr."
NL: "Dhr.", "Mevr."
minLength: 0
maxLength: 20
asset_urls:
type: object
properties:
descriptive:
type: string
example: >-
https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg
description: >-
URL of the descriptive asset. Using this dynamic asset will make
sure that any copy update of Klarna will automatically be
propagated.
standard:
type: string
example: >-
https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg
description: >-
URL of the standard asset. Using this dynamic asset will make sure
that any copy update of Klarna will automatically be propagated.
attachment:
type: object
required:
- body
- content_type
properties:
body:
type: string
example: >-
{"customer_account_info":[{"unique_account_identifier":"[email protected]","account_registration_date":"2017-02-13T10:49:20Z","account_last_modified":"2019-03-13T11:45:27Z"}]}
description: >-
The content of the extra merchant data should be presented as a
string inside this property. The body should be an object containing
any of the keys and sub-objects described below serialized to JSON.
More information on that object can be found
[here](https://docs.klarna.com/api/extra-merchant-data).
content_type:
type: string
example: application/vnd.klarna.internal.emd-v2+json
description: >-
The content type of the body. It is usually represented as
"application/vnd.klarna.internal.emd-v2+json"
authorized_payment_method:
type: object
required:
- type
properties:
number_of_days:
type: integer
format: int32
number_of_installments:
type: integer
format: int32
type:
type: string
enum:
- invoice
- fixed_amount
- base_account
- direct_debit
- direct_bank_transfer
- b2b_invoice
- card
- slice_it_by_card
- pay_later_by_card
- pay_by_card
- fixed_sum_credit
- alternative_payment_method
create_order_request:
type: object
required:
- order_amount
- order_lines
- purchase_country
- purchase_currency
properties:
authorization_token:
type: string
description: Authorization token.
readOnly: true
auto_capture:
type: boolean
description: Allow merchant to trigger auto capturing.
default: false
billing_address:
$ref: '#/components/schemas/address'
custom_payment_method_ids:
type: array
description: >-
Promo codes - The array could be used to define which of the
configured payment options within a payment category (pay_later,
pay_over_time, etc.) should be shown for this purchase. Discuss with
the delivery manager to know about the promo codes that will be
configured for your account. The feature could also be used to
provide promotional offers to specific customers (eg: 0% financing).
Please be informed that the usage of this feature can have
commercial implications.
items:
type: string
customer:
$ref: '#/components/schemas/customer'
locale:
type: string
example: en-GB
description: >-
Used to define the language and region of the customer. The locale
follows the format of [RFC
1766](https://datatracker.ietf.org/doc/rfc1766/), meaning its value
consists of language-country.
Read more on **[Supported Locals and
Currencies](https://docs.klarna.com/klarna-payments/in-depth-knowledge/puchase-countries-currencies-locales/)**.
pattern: ^[A-Za-z]{2,2}(?:-[A-Za-z]{2,2})*$
merchant_data:
type: string
example: >-
{"order_specific":[{"substore":"Women's
Fashion","product_name":"Women Sweatshirt"}]}
description: >-
Pass through field to send any information about the order to be
used later for reference while retrieving the order details (max
6000 characters)
minLength: 0
maxLength: 6000
merchant_reference1:
type: string
example: ON4711
description: >-
Used for storing merchant's internal order number or other
reference.
minLength: 0
maxLength: 255
merchant_reference2:
type: string
example: hdt53h-zdgg6-hdaff2
description: >-
Used for storing merchant's internal order number or other
reference. The value is available in the settlement files. (max 255
characters).
minLength: 0
maxLength: 255
merchant_urls:
$ref: '#/components/schemas/merchant_urls'
order_amount:
type: integer
format: int64
example: 2000
description: >-
Total amount of the order including tax and any available discounts.
The value should be in non-negative minor units. Eg: 25 Euros should
be 2500.
minimum: 0
order_lines:
type: array
description: >-
The array containing list of line items that are part of this order.
Maximum of 1000 line items could be processed in a single order.
items:
$ref: '#/components/schemas/order_line'
maxItems: 1000
minItems: 1
order_tax_amount:
type: integer
format: int64
example: 333
description: >-
Total tax amount of the order. The value should be in non-negative
minor units. Eg: 25 Euros should be 2500.
minimum: 0
payment_method_categories:
type: array
description: Available payment method categories
readOnly: true
uniqueItems: true
items:
$ref: '#/components/schemas/payment_method_category'
purchase_country:
type: string
example: GB
description: >-
The purchase country of the customer. The billing country always
overrides purchase country if the values are different. Formatted
according to ISO 3166 alpha-2 standard, e.g. GB, SE, DE, US, etc.
pattern: ^[A-Za-z]{2,2}$
purchase_currency:
type: string
example: GBP
description: >-
The purchase currency of the order. Formatted according to ISO 4217
standard, e.g. USD, EUR, SEK, GBP, etc.
pattern: ^[A-Za-z]{3,3}$
shipping_address:
$ref: '#/components/schemas/address'
status:
type: string
example: complete
description: >-
The current status of the session. Possible values: 'complete',
'incomplete' where 'complete' is set when the order has been placed.
readOnly: true
enum:
- complete
- incomplete
customer:
type: object
properties:
date_of_birth:
type: string
example: '1978-12-31'
description: Customers date of birth. The format is yyyy-mm-dd
gender:
type: string
example: male
description: Customers gender - male or female
last_four_ssn:
type: string
description: >-
Last four digits of the customer's social security number. This
value is available for US customers.
pattern: ^([0-9]{4}|[0-9]{9})$
national_identification_number:
type: string
description: >-
The customer's national identification number. This value is
available for EU customers utilizing national identification
numbers.
organization_entity_type:
type: string
description: Organization entity type. Only applicable for B2B customers.
enum:
- LIMITED_COMPANY
- PUBLIC_LIMITED_COMPANY
- ENTREPRENEURIAL_COMPANY
- LIMITED_PARTNERSHIP_LIMITED_COMPANY
- LIMITED_PARTNERSHIP
- GENERAL_PARTNERSHIP
- REGISTERED_SOLE_TRADER
- SOLE_TRADER
- CIVIL_LAW_PARTNERSHIP
- PUBLIC_INSTITUTION
- OTHER
organization_registration_id:
type: string
description: Organization registration id. Only applicable for B2B customers.
title:
type: string
example: Mr.
description: |-
Customers Title. Allowed values per country:
UK - "Mr", "Ms"
DE - "Herr", "Frau"
AT: "Herr, "Frau"
CH: de-CH: "Herr, "Frau" it-CH: "Sig.", "Sig.ra" fr-CH: "M", "Mme"
BE: "Dhr.", "Mevr."
NL: "Dhr.", "Mevr."
type:
type: string
example: organization
description: >-
Type of customer in the session. If nothing is added, a B2C session
will be the default. If it is a b2b-session, you should enter
organization to trigger a B2B session.
pattern: ^(person|organization)$
vat_id:
type: string
description: VAT ID. Only applicable for B2B customers.
customer_read:
type: object
properties:
date_of_birth:
type: string
example: '1978-12-31'
description: Customers date of birth. The format is yyyy-mm-dd
gender:
type: string
example: male
description: Customers gender - male or female
organization_entity_type:
type: string
description: Organization entity type. Only applicable for B2B customers.
enum:
- LIMITED_COMPANY
- PUBLIC_LIMITED_COMPANY
- ENTREPRENEURIAL_COMPANY
- LIMITED_PARTNERSHIP_LIMITED_COMPANY
- LIMITED_PARTNERSHIP
- GENERAL_PARTNERSHIP
- REGISTERED_SOLE_TRADER
- SOLE_TRADER
- CIVIL_LAW_PARTNERSHIP
- PUBLIC_INSTITUTION
- OTHER
organization_registration_id:
type: string
description: Organization registration id. Only applicable for B2B customers.
title:
type: string
example: Mr.
description: |-
Customers Title. Allowed values per country:
UK - "Mr", "Ms"
DE - "Herr", "Frau"
AT: "Herr, "Frau"
CH: de-CH: "Herr, "Frau" it-CH: "Sig.", "Sig.ra" fr-CH: "M", "Mme"
BE: "Dhr.", "Mevr."
NL: "Dhr.", "Mevr."
type:
type: string
example: organization
description: >-
Type of customer in the session. If nothing is added, a B2C session
will be the default. If it is a b2b-session, you should enter
organization to trigger a B2B session.
vat_id:
type: string
description: VAT ID. Only applicable for B2B customers.
customer_read_create_token:
type: object
properties:
date_of_birth:
type: string
example: '1978-12-31'
description: Customers date of birth. The format is yyyy-mm-dd
gender:
type: string
example: male
description: Customers gender - male or female
customer_token_creation_request:
type: object
required:
- description
- intended_use
- locale
- purchase_country
- purchase_currency
properties:
billing_address:
$ref: '#/components/schemas/address'
customer:
$ref: '#/components/schemas/customer'
description:
type: string
description: Description of the purpose of the token.
minLength: 1
maxLength: 255
intended_use:
type: string
description: Intended use for the token.
enum:
- SUBSCRIPTION
locale:
type: string
example: en-GB
description: RFC 1766 customer's locale.
pattern: ^[A-Za-z]{2,2}(?:-[A-Za-z]{2,2})*$
purchase_country:
type: string
example: GB
description: ISO 3166 alpha-2 purchase country.
pattern: ^[A-Za-z]{2,2}$
purchase_currency:
type: string
example: GBP
description: ISO 4217 purchase currency.
pattern: ^[A-Za-z]{3,3}$
customer_token_creation_response:
type: object
required:
- token_id
properties:
billing_address:
$ref: '#/components/schemas/address'
customer:
$ref: '#/components/schemas/customer_read_create_token'
payment_method_reference:
type: string
example: 0b1d9815-165e-42e2-8867-35bc03789e00
description: Used to connect customers with payment method when it is present.
redirect_url:
type: string
example: >-
https://credit.klarna.com/v1/sessions/0b1d9815-165e-42e2-8867-35bc03789e00/redirect
description: >-
URL to redirect the customer to after placing the order. This is a
Klarna URL where Klarna will place a cookie in the customers
browser (if redirected) and redirect the customer back to the
confirmation URL provided by the merchant. This is not a mandatory
step but a recommended one to improve the returning customers
experience.
token_id:
type: string
example: 0b1d9815-165e-42e2-8867-35bc03789e00
description: >-
Generated customer token. This token will be used to create a new
order for the subscription using the Create a New order using token
API.
merchant_session:
type: object
required:
- client_token
- session_id
properties:
client_token:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICJzZXNzaW9uX2lkIiA6ICIw
description: >-
Client token to be passed to the JS client while initializing the JS
SDK in the next step.
maxLength: 4096
minLength: 0
payment_method_categories:
type: array
description: Available payment method categories for this particular session
uniqueItems: true
items:
$ref: '#/components/schemas/payment_method_category'
session_id:
type: string
example: 0b1d9815-165e-42e2-8867-35bc03789e00
description: >-
ID of the created session. Please use this ID to share with Klarna
for identifying any issues during integration.
maxLength: 255
minLength: 0
merchant_urls:
type: object
properties:
confirmation:
type: string
example: https://www.example-url.com/confirmation
description: >-
URL of the merchant confirmation page. The consumer will be
redirected back to the confirmation page if the consumer is sent to
the redirect URL after placing the order. Insert {session.id} and/or
{order.id} as placeholder to connect either of those IDs to the
URL(max 2000 characters).
minLength: 0
maxLength: 2000
notification:
type: string
example: https://www.example-url.com/notification
description: >-
URL for notifications on pending orders. Insert {session.id} and/or
{order.id} as placeholder to connect either of those IDs to the URL
(max 2000 characters).
minLength: 0
maxLength: 2000
push:
type: string
example: https://www.example-url.com/push
description: >-
URL that will be requested when an order is completed. Should be
different than checkout and confirmation URLs. Insert {session.id}
and/or {order.id} as placeholder to connect either of those IDs to
the URL (max 2000 characters).
minLength: 0
maxLength: 2000
authorization:
description: >-
URL for receiving the authorization token when payment is completed.
Used for Authorization Callback.
example: https://www.example-url.com/authorization
maxLength: 2000
minLength: 0
type: string
options:
type: object
properties:
color_border:
type: string
example: '#FF9900'
description: >-
Color for the border of elements within the iFrame. Value should be
a CSS hex color, e.g. "#FF9900"
pattern: ^#[A-Fa-f0-9]{6}$
color_border_selected:
type: string
example: '#FF9900'
description: >-
Color for the border of elements within the iFrame when selected by
the customer. Value should be a CSS hex color, e.g. "#FF9900"
pattern: ^#[A-Fa-f0-9]{6}$
color_details:
type: string
example: '#FF9900'
description: >-
Color for the bullet points within the iFrame. Value should be a CSS
hex color, e.g. "#FF9900"
pattern: ^#[A-Fa-f0-9]{6}$
color_text:
type: string
example: '#FF9900'
description: >-
Color for the texts within the iFrame. Value should be a CSS hex
color, e.g. "#FF9900"
pattern: ^#[A-Fa-f0-9]{6}$
radius_border:
type: string
example: 5px
description: Radius for the border of elements within the iFrame.
order:
type: object
required:
- order_id
properties:
authorized_payment_method:
$ref: '#/components/schemas/authorized_payment_method'
fraud_status:
type: string
description: >-
Fraud status for the order. Either ACCEPTED or PENDING. If ACCEPTED,
the order could be captured. If PENDING, please wait till you
receive the notification from Klarna in the notification URL that
the order has been approved. You can find additional information
here.
order_id:
type: string
description: >-
Unique order ID of the transaction. This ID will be used for all
order management processes.
redirect_url:
type: string
example: >-
https://credit.klarna.com/v1/sessions/0b1d9815-165e-42e2-8867-35bc03789e00/redirect
description: >-
URL to redirect the customer to after placing the order. This is a
Klarna URL to which the merchant should redirect the customer to.
Klarna will place a coo
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/klarna/refs/heads/main/openapi/klarna-payments-api-openapi.yml