Klarna Customer Token API
Persist a payment authorization as a customer token for repeat purchases.
OpenAPI Specification
openapi: 3.0.0
info:
description: >-
The Customer Token API is used to charge customers with a tokenized Klarna
payment method and can be used for recurring purchases, subscriptions and
for storing a customer's payment method. Tokens are created using the
[`generate a customer token`](https://docs.klarna.com/api/payments/) call in
the payments API.
version: 1.0.0
title: Klarna Payments API V1
paths:
/customer-token/v1/tokens/{customerToken}:
get:
summary: Get customer token
description: >-
Use this API request to retrieve the content of a Klarna customer token.
The request will return the status of the token as well as payment
method details. To learn more, refer to the **[Read customer tokens
details
article](https://docs.klarna.com/klarna-payments/other-actions/check-the-details-of-a-customer-token/)**.
operationId: readCustomerToken
parameters:
- name: customerToken
in: path
required: true
schema:
type: string
responses:
'200':
description: Token was successfully read.
content:
application/json:
schema:
$ref: '#/components/schemas/customer_token'
'403':
description: You were not authorized to execute this operation.
'404':
description: The token does not exist.
/customer-token/v1/tokens/{customerToken}/order:
post:
summary: Create an order with a customer token
description: >-
Use this API call to create an order using a Klarna Customer Token. Make
sure you use the correct token ID when placing an order, to ensure that
the right consumer gets billed. Read more on **[Create a new order using
the customer
token](https://docs.klarna.com/klarna-payments/integrate-with-klarna-payments/step-3-create-an-order/set-up-a-recurring-payment-order/#create-an-order-with-a-customer-token)**.
operationId: createOrder
parameters:
- name: customerToken
in: path
required: true
schema:
type: string
- name: Klarna-Idempotency-Key
in: header
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/customer_token_order'
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.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorV2'
'403':
description: You were not authorized to execute this operation.
'404':
description: The token does not exist.
'409':
description: The data in the request does not match the session.
/customer-token/v1/tokens/{customerToken}/status:
patch:
summary: Update customer token status
description: >-
Use this API call to update the status of a Klarna Customer Token. This
should be used if you want to cancel a specific customer token. Read
more on **[Update the status of a customer
token](https://docs.klarna.com/klarna-payments/other-actions/cancel-a-customer-token/)**.
operationId: patchCustomerToken
parameters:
- name: customerToken
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/customer_token_status_update_request'
responses:
'202':
description: Token patch request has been accepted and is being processed.
'400':
description: >-
Unable to patch the token with the provided data. Some field
constraint was violated.
'403':
description: You were not authorized to execute this operation.
'404':
description: The token does not exist.
servers:
- url: https://api.klarna.com
components:
schemas:
ErrorV2:
type: object
properties:
authorized_payment_method:
$ref: '#/components/schemas/authorized_payment_method'
correlation_id:
type: string
error_code:
type: string
error_messages:
type: array
items:
type: string
fraud_status:
type: string
reason:
type: string
address:
type: object
properties:
attention:
type: string
example: Attn
description: Attn. - optional parameter.
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.
minLength: 0
maxLength: 99
given_name:
type: string
example: Adam
description: Customers first name.
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: 5
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
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
- pix
- base_account
- deferred_interest
- direct_debit
- direct_bank_transfer
- b2b_invoice
- card
- slice_it_by_card
- pay_later_by_card
- fixed_sum_credit
- pay_by_card
card_information:
type: object
required:
- brand
- expiry_date
- masked_number
properties:
brand:
type: string
example: VISA
description: Card brand
expiry_date:
type: string
example: 12/2020
description: Card expiration date
masked_number:
type: string
example: '************1234'
description: Masked credit card number
customer_token_order:
type: object
required:
- order_amount
- order_lines
- order_tax_amount
- purchase_currency
properties:
attachment:
$ref: '#/components/schemas/attachment'
auto_capture:
type: boolean
description: Allow merchant to trigger auto capturing.
default: false
merchant_data:
type: string
example: >-
{"order_specific":[{"substore":"Women's
Fashion","product_name":"Women Sweatshirt"}]}
description: Pass through field (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. If set, will be shown on the confirmation page as "order
number" (max 255 characters).
minLength: 0
maxLength: 255
merchant_reference2:
type: string
example: ON4711
description: >-
Used for storing merchant's internal order number or other reference
(max 255 characters).
minLength: 0
maxLength: 255
merchant_urls:
$ref: '#/components/schemas/merchant_urls'
order_amount:
type: integer
format: int64
description: >-
Non-negative, minor units. Total amount of the order, including tax
and any discounts.
minimum: 1
order_lines:
type: array
description: The applicable order lines (max 1000)
items:
$ref: '#/components/schemas/order_line'
maxItems: 1000
minItems: 1
order_tax_amount:
type: integer
format: int64
description: Non-negative, minor units. The total tax amount of the order.
minimum: 0
purchase_currency:
type: string
example: GBP
description: ISO 4217 purchase currency.
pattern: ^[A-Za-z]{3,3}$
shipping_address:
$ref: '#/components/schemas/address'
usage:
type: string
readOnly: true
customer_token_status_update_request:
type: object
required:
- status
properties:
status:
type: string
example: CANCELLED
description: The token status to update to.
enum:
- CANCELLED
customer_token:
type: object
required:
- payment_method_type
- status
properties:
card:
$ref: '#/components/schemas/card_information'
direct_debit:
$ref: '#/components/schemas/direct_debit_information'
payment_method_type:
type: string
example: INVOICE
description: Selected payment method
status:
type: string
example: ACTIVE
description: Status of token, can be active, cancelled, suspended
direct_debit_information:
type: object
required:
- masked_number
properties:
masked_number:
type: string
example: '**********124'
description: Masked bank account number
merchant_urls:
type: object
required:
- confirmation
properties:
confirmation:
type: string
description: URL of merchant confirmation page. (max 2000 characters)
minLength: 0
maxLength: 2000
push:
type: string
description: >-
URL that will be requested when an order is completed. Should be
different than checkout and confirmation URLs. (max 2000 characters)
minLength: 0
maxLength: 2000
order:
type: object
required:
- fraud_status
- order_id
- redirect_url
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 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. It is a spontaneous
step and does not harm the customers experience.
order_line:
type: object
required:
- name
- quantity
- total_amount
- unit_price
properties:
image_url:
type: string
example: https://www.exampleobjects.com/logo.png
description: >-
URL to an image that can be later embedded in communications between
Klarna and the customer. (max 1024 characters).
A minimum of 250x250 px resolution is recommended for the image to look good in the Klarna app, and below 50x50 px won't even show. We recommend using a good sized image (650x650 px or more), however the file size must not exceed 12MB.
minLength: 0
maxLength: 1024
merchant_data:
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: >-
Used for storing merchant's internal order number or other
reference. Pass through field. (max 255 characters)
minLength: 0
maxLength: 255
name:
type: string
example: Running shoe
description: Descriptive name of the order line item.
minLength: 1
maxLength: 255
product_identifiers:
$ref: '#/components/schemas/product_identifiers'
product_url:
type: string
example: https://.../AD6654412.html
description: >-
URL to the product in the merchants webshop that can be later used
in communications between Klarna and the customer. (max 1024
characters)
minLength: 0
maxLength: 1024
quantity:
type: integer
format: int64
example: 1
description: Quantity of the order line item. Must be a non-negative number.
minimum: 0
quantity_unit:
type: string
example: pcs
description: >-
Unit used to describe the quantity, e.g. kg, pcs, etc. If defined
the value has to be 1-8 characters.
reference:
type: string
example: AD6654412
description: >-
Client facing article number, SKU or similar. Max length is 256
characters.
minLength: 0
maxLength: 256
tax_rate:
type: integer
format: int64
example: 1900
description: >-
Tax rate of the order line. Non-negative value. The percentage value
is represented with two implicit decimals. I.e 1900 = 19%.
total_amount:
type: integer
format: int64
example: 2500
description: >-
Total amount of the order line. Must be defined as non-negative
minor units. Includes tax and discount. Eg: 2500=25 euros
Value = (quantity x unit_price) - total_discount_amount.
(max value: 100000000)
maximum: 100000000
total_discount_amount:
type: integer
format: int64
example: 500
description: 'Non-negative minor units. Includes tax. Eg: 500=5 euros'
minimum: 0
total_tax_amount:
type: integer
format: int64
example: 475
description: >-
Total tax amount of the order line. Must be within �1 of
total_amount - total_amount 10000 / (10000 + tax_rate). Negative
when type is discount.
type:
type: string
enum:
- physical
- discount
- shipping_fee
- sales_tax
- digital
- gift_card
- store_credit
- surcharge
example: physical
description: Type of the order line item.
unit_price:
type: integer
format: int64
example: 2500
description: >-
Price for a single unit of the order line. Non-negative minor units.
Includes tax, excludes discount. (max value: 100000000)
maximum: 100000000
subscription:
$ref: '#/components/schemas/subscription'
product_identifiers:
type: object
properties:
brand:
type: string
example: shoe-brand
description: >-
The product's brand name as generally recognized by consumers. If no
brand is available for a product, do not supply any value.
minLength: 0
maxLength: 70
category_path:
type: string
example: Shoes > Running
description: >-
The product's category path as used in the merchant's webshop.
Include the full and most detailed category and separate the
segments with ' > '
minLength: 0
maxLength: 750
global_trade_item_number:
type: string
example: '4912345678904'
description: >-
The product's Global Trade Item Number (GTIN). Common types of GTIN
are EAN, ISBN or UPC. Exclude dashes and spaces, where possible
minLength: 0
maxLength: 50
manufacturer_part_number:
type: string
example: AD6654412-334.22
description: >-
The product's Manufacturer Part Number (MPN), which - together with
the brand - uniquely identifies a product. Only submit MPNs assigned
by a manufacturer and use the most specific MPN possible
minLength: 0
maxLength: 70
color:
type: string
example: white
description: Color to be shown to the end customer (max 64 characters).
minLength: 0
maxLength: 64
size:
type: string
example: small
description: Size to be shown to the end customer (max 64 characters).
minLength: 0
maxLength: 64
subscription:
type: object
required:
- name
- interval
- interval_count
properties:
name:
description: The name of the subscription product
type: string
interval:
description: The cadence unit for this.
type: string
enum:
- DAY
- WEEK
- MONTH
- YEAR
interval_count:
description: The number of intervals
type: integer
minimum: 1