Handle token order failures effectively by initiating a new Klarna session without the token, allowing customers to restart the purchase journey and complete the transaction.
This article explains the recovery process to handle failures when placing an order using a customer token in Klarna’s tokenized payment setup.
This recovery flow can only be triggered in cases where you are sure the customer is present as this flow requires customer interaction to be successful.
If a payment attempt using a customer token fails while the customer is active in the session, Klarna may return an error indicating that the saved token can’t be used to complete the transaction.
In these cases, a partner should fallback to creating a new payment session to complete the order. This allows the customer to enter the purchase flow and potentially correct the issue(s) causing the token charge to fail. If the purchase is successful, the customer token will be recovered, meaning it can now be successfully charged, and this purchase will be connected to the customer token.
Monitor Klarna responses to the create order from a customer token API call. It is recommended to attempt a fallback purchase flow if you receive the UNAVAILABLE_PAYMENT_METHOD error code below in the response. If the response contain error code PAYMENT_METHOD_FAILED then the recommendation is to retry the token charge.
| HTTP Status | Error code | Description | Action |
|---|---|---|---|
| 403 Forbidden |
| Klarna was unable to charge the customer token due to a funding source issue. | Fallback purchase flow |
| 403 Forbidden |
| Klarna was unable to charge the customer token due to a temporary issue with the payment method. | Retry token charge |
Consult this page for a complete list of validations during the payment process.
Klarna can be integrated into your website in two different ways, depending on your setup and preferred level of customization. Each option has its own implementation steps and requirements:
Follow the instructions that correspond to the integration method you've chosen to ensure a smooth and reliable setup.
For a complete overview of Klarna Payment SDK based Integration, see the detailed documentation here.
Klarna Payment SDK must be added to any page where the fallback purchase flow may be required.
Step 1: Create a new one-time Klarna session
Use Klarna’s create session endpoint to create a new one-time-buy session. The intent must be set to buy for all fallback purchase flow transactions. The customer_token from the failed charge must be provided as part of the customer object.
Sample request
"acquiring_channel": "ECOMMERCE",
"intent": "buy",
"customer": {
"customer_token": "<customer_token>"
}
"purchase_country": "US",
"purchase_currency": "USD",
"locale": "en-US",
"order_amount": 9500,
"order_tax_amount": 1900,Sample response
{
"session_id": "068df369-13a7-4d47-a564-62f8408bb760",
"client_token": "<client_token>",
"payment_method_categories": [
{
"identifier": "klarna",
"name" : "Pay with Klarna",
"asset_urls" : {
"descriptive" : "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg",
"standard" : "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg"Store the client_token from the response.
Step 2: Initialize the Klarna widget and authorize the purchase
Using the client_token from the session response and initialize the Klarna modal. You can immediately trigger the Klarna Purchase Flow by calling authorize() via the Klarna Payment SDK.
Sample request
Klarna.Payments.init({
client_token: "<client_token>"
});
Klarna.Payments.authorize(
{},
{
shipping_address: {
given_name: "John",
family_name: "Doe",There are two ways to retrieve the authorization_token:
- Client-side: Returned as part of the
authorize()call. - Server-side: Provided through an authorization callback url configured in the
create_sessioncall.
If the customer is declined at this stage, redirect them back to the checkout to select a different payment method.
Step 3: Create the order
For a successfully authorized purchase you can use the returned authorization_token to create the order:
Path parameter
| Parameter name | Description |
|---|---|
| Token issued by Klarna that represents a consumer's approval for a payment session. |
Sample request
{
"purchase_country": "US",
"purchase_currency": "USD",
"locale": "en-US"
"shipping_address": {
"given_name": "John",
"family_name": "Doe",
"email": "john@doe.com",
"title": "Mr",
"street_address": "Lombard St 10",Sample response
{
"order_id": "3eaeb557-5e30-47f8-b840-b8d987f5945d",
"redirect_url": "https://payments.klarna.com/redirect/...",
"fraud_status": "ACCEPTED",
"authorized_payment_method": "invoice"
}
Once a purchase is successfully created, it will be automatically linked to the existing customer token, and the same token can then used to charge future purchases.
For a complete overview of Klarna’s Hosted Payment Page integration, see the detailed documentation here.
Step 1: Create a new one-time Klarna session
Use Klarna’s create session endpoint to create a new one-time-buy session. The intent must be set to buy for all fallback purchase flow transactions. The customer_token from the failed charge must be provided as part of the customer object.
Sample request
{
"acquiring_channel": "ECOMMERCE",
"intent": "buy",
"customer": {
"customer_token": "<customer_token>"
}
"purchase_country": "US",
"purchase_currency": "USD",
"locale": "en-US"
"shipping_address": {Sample response
{
"session_id": "068df369-13a7-4d47-a564-62f8408bb760",
"client_token": "<client_token>",
"payment_method_categories": [
{
"identifier": "klarna",
"name": "Pay with Klarna",
"asset_urls": {
"descriptive": "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg",
"standard": "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg"Store the session_id from the response.
Step 2: Create a Hosted Payment Page session
Associate the Klarna Payments session_id from step 1 with the Hosted Payment Page session by including it in the payment_session_url when creating the HPP session.
| Parameter | Presence | Description |
|---|---|---|
| required | URL of the KP Session, obtained in the first step, to be hosted by the HPP Session. | |
| optional | It determines whether the place order operation is handled by the Hosted Payment Page or by your own system. Possible values are:
|
Sample request
{
"merchant_urls": {
"back": "https://example.com/back?sid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&hppId={{session_id}}",
"cancel": "https://example.com/cancel?sid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&hppId={{session_id}}",
"error": "https://example.com/error?sid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&hppId={{session_id}}",
"failure": "https://example.com/fail?sid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&hppId={{session_id}}",
"status_update": "https://example.com/status_update?sid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&secret=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy&hppId={{session_id}}",
"success": "https://example.com/success?sid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&hppId={{session_id}}&token={{authorization_token}}"
},
"options": {Sample response
{
"distribution_module": {
"generation_url": "string",
"standalone_url": "string",
"token": "string"
},
"distribution_url": "https://api.klarna.com/hpp/v1/sessions/9cbc9884-1fdb-45a8-9694-9340340d0436/distribution",
"expires_at": "2038-01-19T03:14:07.000Z",
"manual_identification_check_url": "https://api.klarna.com/hpp/v1/sessions/9cbc9884-1fdb-45a8-9694-9340340d0436/manual-id-check",
"qr_code_url": "https://pay.klarna.com/eu/hpp/payments/a94e7760-d135-2721-a538-d6294ea254ed/qr",Step 3: Redirect customers to the Hosted Payment Page and Monitor the Authorization status
Redirect the customer to the Hosted Payment Page using the redirect_url provided in the session creation response. You may optionally display a prompt or call-to-action before initiating the redirect.
To track the session status, either:
- Configure a Klarna webhook to receive asynchronous updates.
- Poll Klarna’s API to retrieve the result of the session.
Refer to the HPP session lifecycle for a detailed explanation of how the session progresses and how to handle its different states.
If the payment is declined, redirect the customer back to checkout so they can choose another payment method.
Step 4: Create the order
If the HPP session was created using PLACE_ORDER and CAPTURE_ORDER modes, Klarna handles the order creation, and an order_id is returned, no further action is needed.
When the session was created using place_order_mode: NONE, Klarna does not create the order automatically.
Use the returned authorization_token returned upon successful authorization to create the order:
Path parameter
| Parameter name | Description |
|---|---|
| Token issued by Klarna that represents a consumer's approval for a payment session. |
Sample request
{
"purchase_country": "US",
"purchase_currency": "USD",
"locale": "en-US"
"shipping_address": {
"given_name": "John",
"family_name": "Doe",
"email": "john@doe.com",
"title": "Mr",
"street_address": "Lombard St 10",Sample response
{
"order_id": "3eaeb557-5e30-47f8-b840-b8d987f5945d",
"redirect_url": "https://payments.klarna.com/redirect/...",
"fraud_status": "ACCEPTED",
"authorized_payment_method": "invoice"
}
Once a purchase is successfully created, it will be automatically linked to the existing customer token, and the same token can then used to charge future purchases.