With a previously created payment:customer_present
scope token, customers can use Klarna for an on-demand payment:
customer_token
or the token equivalent issued by the Acquiring Partner, interoperability_token
and interoperability_data
.customer_token
step_up_config
request_payment_transaction
APPROVED
– Depending on risk assessment and the initially selected payment method, charges might go through immediately as a one-click experience. Transaction is completed, proceed to confirmation and store payment_transaction_id
.STEP_UP_REQUIRED
– In certain cases, customers are required to go through a step-up flow. Acquiring Partners have to either return the klarna payment_request_id
or payment_request_url
to the Partner.DECLINED
– If the payment is denied, Acquiring Partners have to inform the Partner that the payment could not be completed, the Partner should invite the customer to select another payment method.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\":{...}}}"
}
}
}
Supplementary purchase data improves Klarna’s ability to assess risk, optimize approval rates, and deliver a more personalized checkout experience. It includes structured information such as line items, L2/L3 data for Card Network optimization and other transaction context.
Acquiring Partners may receive this data from the Partner in two ways:
interoperability_data
supplementary_purchase_dataAPI
object when calling the Payment Authorize APIAPI.
Acquiring Partner must collect and forward data that aligns with Klarna’s Supplementary Purchase Data package by utilizing their existing schema.
Acquiring Partner should not add additional fields of the supplementary purchase data in their APIs to support Klarna. Instead, they must ensure that the interoperability_dataAPI
and its required structure are properly implemented.
In both cases, the Acquiring Partner is responsible for ensuring that the data provided by the Partner is accurately forwarded to Klarna. Partners should not be asked to resubmit the same information through multiple mechanisms.
Read more about Supplementary Purchase Data here.
/v2/accounts/{partner_account_id}/payment/authorize
Parameter | Required | Description |
---|---|---|
Copied Klarna-Customer-Token | No | The customer token represents the tokenized customer and allows you to act on behalf of the customer. |
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. |
For customer present token charges it is not required to submit the ondemand_services
supplementary purchase data.
Sample On-demand request with existing token
curl -X POST "https://api-global.klarna.com/v2/payment/authorize" \
-H 'Authorization: Basic <base64(api_key:api_secret)>' \
-H 'Content-Type: application/json' \
-H 'Klarna-Interoperability-Token: eyJhbGciOiJIU...' \
-H 'Klarna-Customer-Token: krn:customer-token:123' \
-d '{
"currency": "USD",
"supplementary_purchase_data": {
"line_items": [
{
The Payment Authorize API can yield 3 different outcomes depending on the transaction and the consumer:
Result | Description |
---|---|
| The Payment Authorization is approved without additional customer interaction. A Payment Transaction is created and contained in the response. |
| Additional customer interaction is required to authorize the payment. Those interactions need to happen in Klarna’s Purchase Journey and the customer has to be redirected to it. Read more about how to handle the Step-up Scenario. |
| The payment cannot proceed due to reasons such as fraud, final decline or risk concerns. |
When the request is successful, a Payment Transaction is created on Klarna Network and will be available for post-purchase operations through the Payment Transactions API. 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 order confirmation page.
Acquiring Partners must 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.
The response will contain a payment_transaction_responseAPI
object with the following parameters:
Parameter name | Description |
---|---|
The result parameter which specifies the outcome of the authorization.In case of a successful Authorization the result will be set to APPROVED | |
The payment_transaction object represents a single payment transaction This object is only returned if the payment_transaction_response.result is set to APPROVED The payment_transaction_idAPI returned is necessary to manage the Payment Transaction through the Payment Transaction APIAPI. |
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 transaction could not be approved by Klarna and step-up scenario cannot be triggered (due to missing configuration or for permanent decline), the Acquiring Partner will receive a decline. Declines should not be replayed without change of context.
The Acquiring Partner should inform the Partner that the payment could not be completed and the Partner should invite the customer to select another payment method.
The response will contain a payment_transaction_responseAPI
object with the following parameters:
Parameter name | Description |
---|---|
The result parameter which specifies the outcome of the authorization.In case of a decline, the result will be set to DECLINED |
Sample response - DECLINED
{
"payment_transaction_response": {
"result": "DECLINED"
}
}
When a Payment Transaction could not be immediately created by Klarna and a step-up configuration was provided in the call to the Payment Authorization API, the Step-up scenario will be triggered and the Acquiring Partner will receive a STEP_UP_REQUIRED
result.
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.
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 complete the payment, usually triggering authentication and payment option selection. The required work 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.
Parameter name | Description |
---|---|
The payment_transaction_response object will contain the resultAPI parameter which specifies the outcome of the the authorization.In case of the Step up flow the result will be set to STEP_UP_REQUIRED | |
The base properties of a Payment Request. This field is only returned if the payment_transaction_response.resultAPI is set to STEP_UP_REQUIRED .The state_context.customer_interactionAPI object contains:
|
Sample response - STEP_UP_REQUIRED
{
"payment_transaction_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",