Steps for token creation only or for token creation with purchase:
interoperability_token
and interoperability_data
for:supplementary_purchase_data
ondemand_service
orsubscription
and/orline_items[]
if a purchase is involvedstep_up_config
request_customer_token
request_payment_transaction
payment_request_id
or payment_request_url
to the Partner.Before calling Klarna’s Payment Authorization API, the Acquiring Partner must ensure their backend accept and forward Klarna specific parameters. These include interoperability parameters that preserve session context as well as supplementary purchase data which improves Klarna’s ability to assess risk, optimize approval rates, and deliver a more personalized checkout experience.
When Partners optimize their integration with Klarna, they are likely to have interoperability parameters to share with the Acquiring Partner.
Parameter | Purpose |
---|---|
| Encodes Klarna-specific session context (e.g., preselected payment option, pre-qualification results). |
| Submit supplementary purchase data directly to Klarna |
These ensure consistent customer and transaction context throughout the payment flow and must be forwarded unaltered to Klarna.
Implementation requirements
The Partner-facing field should be named either klarna_interoperability_token
/klarna_interoperability_data
or interoperability_token
/interoperability_data
in a Klarna-specific context, ensuring that it’s easy for any Partner to identify and use.
The Acquiring Partner can validate the input based on the provided guidelines but must not modify it. The input must always be forwarded as received, without any interference.
Sample request
Below an example of how Acquiring Partners can accept the interoperability parameters in their Payment request API endpoint.
{
"currency": "USD",
"amount": 17800,
"payment_method_options": {
"klarna": {
"interoperability_token": "eyJhbGciOiJ...",
"interoperability_data": "{\"content_type\":\"application/vnd.klarna.interoperability-data.v2+json\",\"content\":{\"payment_request\":{...}}}"
}
}
}
/v2/accounts/{partner_account_id}/payment/authorize
Parameter | Required | Description |
---|---|---|
Copied partner_account_id | Yes | Unique account identifier assigned by Klarna to the onboarded merchant |
To support tokenized payments, Acquiring Partners must include additional parameters when calling the Authorization APIAPI. Klarna then generates a customer token, which authorizes future payments on behalf of the customer. Each customer token is issued with specific scopes that define the permitted actions and level of access for subsequent transactions.
Scope | Definition | Use cases |
---|---|---|
| Enables tokenization of the customer for subsequent on-demand charges. Depending on risk assessment and the initially selected payment method, charges might go through immediately as a one-click experience or, in certain cases, require a step-up. |
|
| Enables tokenization of the customer for subsequent subscription charges. It allows the Partners to initiate tokens charges without requiring a step-up flow since the customer is not present during the transaction. |
|
Creating a token with multiple token scopes will be supported in the future.
Choosing the correct token scope is crucial for ensuring successful payments and maximizing conversion:
payment:customer_present
: choose this token scope for payments where the customer is actively present in the payment flow and can authenticate if required, so it's not suitable for subscription charges.payment:customer_not_present
: choose this token scope for payments where the customer is not present in the payment flow. While this scope could also work for a customer present payment, there may be limitations in the payment options Klarna can offer under this scope./v2/accounts/{partner_account_id}/payment/authorize
Parameter | Required | Description |
---|---|---|
Copied Klarna-Interoperability-Token | No | The interoperability token enables continuity of customer journey across domains and services. If you are an Acquiring Partner, you receive this token from your merchant. |
Note that the request_payment_transaction
is only required in case of token creation with purchase.
The Payment Authorize API response for the payment_transaction_response
and for the customer_transaction response
can yield 3 different results:
Result | Description |
---|---|
| The customer has to authenticate for the token creation and, if applicable, for the payment. Read more about how to handle the Step-up Scenario. |
| Successful creation of the customer token and, if applicable, the payment transaction. |
| Token creation and if applicable, the payment authorization are declined. |
/v2/accounts/{partner_account_id}/payment/authorize
Parameter | Required | Description |
---|---|---|
Copied payment_transaction_response | No | The request for a payment transaction can result in one of the following outcomes:
|
Copied -result | Yes | The result of the authorization attempt |
Copied -payment_transaction | Yes | The Payment Transaction object represents a single payment transaction. |
Copied --payment_transaction_id | No | Unique identifier for a created Payment Transaction. This identifier can be used to manage the Payment Transaction through the Payment Transaction API. You should not make any assumption about the format of this identifier, you should trea... Show more |
Copied --payment_transaction_reference | No | Reference to the payment or equivalent resource created on your side. This will be exposed in the Payment Transaction webhooks for the purpose of correlating your resource with the Klarna Payment Transaction. |
Copied --state | No | The current state of the Payment Transaction.
|
Copied --currency | No | Currency in ISO 4217 format. |
Copied --amount | No | Total amount of a one-off purchase, including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500. This is the amount that Klarna will charge the customer for a one-off purchase. S... Show more |
Copied --payment_pricing | No | Payment pricing details |
Copied ---applicable_rate | Yes | Applicable rate for the payment |
Copied ----fixed_fee | Yes | Applicable fixed fee for the payment. The value is negative when representing an incentive. It is present as per the currency applicable for the fixed fee for that transaction. |
Copied -----amount | Yes | Numeric without decimals. Minor currency units (e.g. cent, öre) following ISO 4217, must use with Currency. |
Copied -----currency | Yes | Currency in ISO 4217 format. |
Copied ----variable_fee | Yes | Variable fee is the percentage of the payment amount. The value is negative when representing an incentive. |
Copied -----percentage | Yes | Percentage points representing the percent value multiplied by 100. For example, 1.5% is represented as 150. |
When the customer has to authenticate for the token creation, and optionally also for the purchase completion, the Step-up scenario will be triggered and the Acquiring Partner will receive a STEP_UP_REQUIRED
result.
In such scenario, the Payment Authorization API returns a Payment Request in the response. The expectation is that the customer will go through Klarna’s Purchase Journey to authenticate for the token creation and, if required, to complete the purchase. The required steps to properly make the step-up scenario work is outlined in the next section.
The following parameters are present in the response to the request.
Token creation with purchase -Sample response - STEP_UP_REQUIRED
{
"payment_transaction_response": {
"result": "STEP_UP_REQUIRED"
},
"customer_token_response": {
"result": "STEP_UP_REQUIRED"
},
"payment_request": {
"payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
"payment_request_reference": "acquiring-partner-request-reference-1234",
Token creation without purchase -Sample response - STEP_UP_REQUIRED
{
"customer_token_response": {
"result": "STEP_UP_REQUIRED"
},
"payment_request": {
"payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
"payment_request_reference": "acquiring-partner-request-reference-1234",
"amount": 11800,
"currency": "USD",
"state": "SUBMITTED",
In case your systems cannot support a pattern where there is no consumer interaction at the initialization of the session, it is possible to force the Step-up flow. This can be achieved by adding the mode = REQUIRED
to the step_up_config
object.
The mode = REQUIRED
will be available in a future release.
When the token creation is successful, a customer_token
is created on the Klarna Network. Optionally, if a purchase is completed, a payment_transaction_id
is created too. No further customer interactions are needed and the Acquiring Partner can directly inform their partners that the payment session is completed and that the customer can be redirected to the confirmation page.
Acquiring Partners must share the Klarna customer_token
or issue their own token equivalent and share it with their Partners to enable them to perform future token charges. Acquiring Partners must also store the Klarna payment_transaction_id
for future operations on the transaction through the Payment Transactions API, such as capture and refund. The Acquiring Partner will receive the following parameters in the response.
Sample response - APPROVED
{
"customer_token_response": {
"result": "APPROVED",
"customer_token": "krn:customer-token:123"
}
}
Sample response - APPROVED
{
"payment_transaction_response": {
"result": "APPROVED",
"payment_transaction": {
"payment_transaction_id": "krn:payment:eu1:transaction:6debe89e-98c0-[...]",
"payment_transaction_reference": "acquiring-partner-transaction-reference-1234",
"amount": 11800,
"currency": "USD",
"payment_funding": {...},
"payment_pricing": {...}
If a token creation request, optionally with a purchase, could not be approved by Klarna and the step-up scenario cannot be triggered (due to missing configuration or a permanent decline), the Acquiring Partner will receive a DECLINED result. Declines should not be replayed without a change of context. The Acquiring Partner should inform the Partner that the token creation, and the transaction if applicable, could not be completed.
Sample response - DECLINED
{
"customer_token_response": {
"result": "DECLINED"
}
}
Sample response - DECLINED
{
"payment_transaction_response": {
"result": "DECLINED"
},
"customer_token_response": {
"result": "DECLINED"
}
}
When creating a token with a purchase, it’s possible—though rare—for the payment transaction and customer token results to differ. The list below summarizes each scenario and the appropriate next steps:
APPROVED
(transaction), STEP_UP_REQUIRED
(token): Register payment_transaction_id
, then direct the customer to the step-up flow to complete token authentication.STEP_UP_REQUIRED
(transaction), APPROVED
(token): Register customer_token
, then direct the customer to the step-up flow to complete the purchase.APPROVED
(transaction), DECLINED
(token): Retrieve payment_transaction_id
; token creation failed—notify the partner to inform the transaction.DECLINED
(transaction), APPROVED
(token): Retrieve and save customer_token
for future use; purchase failed—notify the partner to inform the customer. May use the customer_token
to reattempt the charge on the background if customer_not_present scope was requested.