Use the customer_token to create a payment request using the Partner Product API. The approach to create a payment request using the customer token depends on the use case. Select the option that fits your Partners business model and follow the integration steps.
Please note that the type of token charge initiated also requires the adequate scope set on the customer token. Token charges with mismatching scopes may be rejected. See Customer token scopes for more details.
Support for displaying Klarna as a saved payment method will be added in a subsequent release. In the meantime, we recommend showing the Klarna logo and “Klarna” as the name of the payment method.
When the customer is present, include the customer token in the Klarna-Customer-Token header when creating a token charge request from your server. This parameter is included in the header to optimize the response time of the request. For a successful request, ensure the following parameters are included:
| Parameter | Definition |
|---|---|
currency | The currency in which the transaction is made. |
payment_amount | The total amount to be charged. |
ondemand_profile.reference | The same reference specified when creating the customer token must be passed in when charging the token to ensure the customers payment preferences will be applied correctly. |
config.customer_present | Set customer_present to true to indicate that the customer is present in your checkout flow and can if need be fulfill a step-up authentication request made by Klarna. |
config.redirect_url | Share a redirect_url that will be used to redirect the customer to the Klarna Payment flow if Klarna requests step-up authentication. |
Consult the API reference for a complete description of the request body parameters. Configurations for a customer present token charge is detailed below.
Support for ondemand objects will be added in a subsequent release.
Example for Charge Token when customer initiates the transaction
The following example reflects a customer being charged for a Banana Split totaling $25 USD. This purchase is initiated directly by the customer, reflected by customer_present=true.
In certain situations, customer input is needed when charging a customer token. This might happen when additional authentication is requested by Klarna or an issuing bank or when Klarna does not have valid payment method details on file for the customer.
In this scenario, the response from the token charge request will return a 200 status code and the status of the payment request being SUBMITTED. Klarna will also share a distribution URL to be used to redirect the user to the Klarna Payment flow.
After redirecting the customer and the customer has completed the Klarna Payment flow, a payment_confirmation_token is returned and the payment request must be confirmed similarly to when creating a customer token the first time, transitioning the status of the payment request to CONFIRMED. The customer_token will not generally be updated in this case.
If the payment request has not been confirmed within 24 hours, the payment request will transition to DECLINED. In this case, the Partner must notify their customer to return to their checkout to complete the payment (for example, by sending an email or push notification).
See more information about how to handle rejections here.
When the customer is not present, use the customer token to create a token charge request from your server including the following parameters in the request:
| Parameter | Definition |
|---|---|
currency | The currency in which the transaction is made. |
payment_amount | The total amount to be charged. |
subscription.subscription_reference | The same reference specified when creating the customer token must be passed in when charging the token to ensure the customers payment preferences will be applied correctly. |
subscription.name | The name of the subscription. This will be shown to the customer in the Klarna App. |
subscription.subscription_plan | Specifies the billing amount, interval and interval frequency of the subscription plan. This will be shown to the customer in the Klarna App.This is also used to determine eligible payment methods in the token charge. |
config.customer_present | Set customer_present to false to indicate that the customer is not present in your checkout flow during the attempt and can’t fulfill a step-up authentication request made by Klarna. |
Consult the API reference for a complete description of the request body parameters. Configurations for a customer present token charge is detailed below.
Support for subscription objects will be added in a subsequent release.
Example for Charge Token when customer is not present
Consult Handling rejections to set up support to handle non-successful payments.
Customer tokens issued by Klarna do not expire. However, to ensure backwards compatibility and enhanced security, Klarna can rotate and issue a new customer token in the response of a token charge request.
To ensure seamless continuity of using customer tokens, acquiring partners must support exchanging the stored customer_token whenever the token shared in the response has been updated, regardless of if it is a customer present or not present token charge.
Example of customer token rotation
When the payment request has been successfully submitted, Klarna will return an HTTP 201. The response body will contain the payment_request_id as well as the updated customer_token that has to be stored to be able to initiate future payments for the customer using the token.
A decline code is typically a HTTP error code that indicates a reason for the decline. While the code can originate from a number of sources, it often comes due to credit assessment, the issuing bank or the payment processor.
Klarna uses its own decline codes, which simplifies error handling in comparison to traditional decline codes, but defines the resolution more clearly. Use the following table to help resolve issues relating to token charge decline codes:
| HTTP Status Code | State | State Reason | Definition |
|---|---|---|---|
200 | DECLINED | CUSTOMER_ACTION_REQUIRED | Temporary rejection most likely caused by insufficient funds or Klarna not having valid payment method details on file in a customer not present token charge. The rejection has been communicated to the customer by Klarna, but the Partner can instruct the customer to open the Klarna App for instructions on how to resolve the issue. The Partner can reattempt to charge the customer token again within 24 hours. |
200 | DECLINED | PERMANENT | Permanent rejection. You must sign up the customer again. |
200 | SUBMITTED |
Other decline reasons are technical in nature and the Partner can retry again once confirming all details shared were correct when initiating the token charge. Consult the API reference for a complete description of the possible decline codes and resolution.