Klarna Docs - Handle token order failure

Handle token order failure

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.

If a payment attempt using a customer token fails while the customer is active in the payment request, Klarna may return an error indicating that the token can’t be used to complete the transaction.

In this scenario, the integrator should create a new Klarna session without the token. This fallback lets the customer re-enter the Klarna Purchase Journey and receive a new, real-time underwriting decision.

Server-side error based trigger

Monitor Klarna responses to the create order from a customer token API call. If the response includes the error code below, Klarna recommends triggering a fallback flow by creating a new payment request without the token.

HTTP Status	Error code	Description	Action
403 Forbidden	Example: `UNAVAILABLE_PAYMENT_METHOD`	Klarna was unable to charge the customer token due to a funding source issue.	Fallback purchase flow

Consult this page for a complete list of validations during the payment process.

Flow overview

flowchart TD A[Token-based purchase attempt falls, on-session] -->B[Klarna returns error response with failure session] B --> C[Is the failure reason a fallback trigger?] C -->|No| D[Handle error normally or renty token flow] C -->|Yes| E[Create new Klarna Payments session] E --> F{Integration type} F -->|SDK| G[Use client_token to init Klarna SDK] F -->|Server-side| H[Create HPP session using KP session_id] G --> I[Call authorize to render Klarna widget] H --> J[Redirect customer to Klarna using redirect_url] I --> K[Customer completed authorization] J --> K[Customer completed authorization] K --> L[Use authorization_token to create order server-side]

Fallback flow limitations

The fallback order is not linked to the original customer token.
The order will not appear in the Klarna App under subscriptions.
The customer token is not refreshed or updated.

Fallback implementation

Klarna SDK integration

Klarna 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.

Sample request

JSON

{
  "acquiring_channel": "ECOMMERCE",
  "intent": "buy",
  "purchase_country": "SE",
  "purchase_currency": "SEK",
  "locale": "en-SE",
  "order_amount": 9500,
  "order_tax_amount": 1900,
  "order_lines": [
    {

Store the client_token from the response:

JSON

{
  "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"

Step 2: Initialize and render Klarna widget

Using the client_token from the response, initialize the Klarna modal for the session.

JAVASCRIPT

Klarna.Payments.init({
  client_token: "<client_token>"
});

Step 3: Authorize the transaction

Trigger the Klarna widget by calling authorize() via the SDK

Sample request

JAVASCRIPT

Klarna.Payments.authorize(
  {},
  {
    billing_address: {
      given_name: "Alice",
      family_name: "Test",
      email: "customer@email.se",
      street_address: "Södra Blasieholmshamnen 2",
      postal_code: "11 148",
      city: "Stockholm",

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_session call.

If the customer is declined at this stage, redirect them back to the checkout to select a different payment method.

Step 4: Create the order

Use the returned authorization_token in the path of the create order:

Path parameter

Parameter name	Description
`authorizationToken`	Token issued by Klarna that represents a consumer's approval for a payment session.

Sample request

JSON

{
  "purchase_country": "US",
  "purchase_currency": "USD",
  "billing_address": {
    "given_name": "John",
    "family_name": "Doe",
    "email": "john@doe.com",
    "title": "Mr",
    "street_address": "Lombard St 10",
    "street_address2": "Apt 214",

Server-Side (Hosted Payment Page) integration

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.

Sample request

JSON

{
  "acquiring_channel": "ECOMMERCE",
  "intent": "buy",
  "purchase_country": "SE",
  "purchase_currency": "SEK",
  "locale": "en-SE",
  "order_amount": 9500,
  "order_tax_amount": 1900,
  "order_lines": [
    {

Sample response

JSON

{
  "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 Hosted Payment Page session

Include the session_id in the payment_session_url when sending the HPP request.

Sample request

JSON

{
  "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

JSON

{
  "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 customer to HPP and Monitor for authorization status

Redirect the customer to the Hosted Payment Page using the data returned in the response. You can optionally display a prompt or call-to-action button before redirecting.

To monitor the payment request status, use either a Klarna webhook or poll Klarna’s API to retrieve the authorization_token.

If the payment is declined, redirect the customer back to checkout so they can choose another payment method.

Consul the HPP session lifecycle for a complete description of the payment monitoring.

Step 4: Create the order

Use the returned authorization_token in the path of the create order:

Path parameter

Parameter name	Description
`authorizationToken`	Token issued by Klarna that represents a consumer's approval for a payment session.

Sample request

JSON

{
  "purchase_country": "US",
  "purchase_currency": "USD",
  "billing_address": {
    "given_name": "John",
    "family_name": "Doe",
    "email": "john@doe.com",
    "title": "Mr",
    "street_address": "Lombard St 10",
    "street_address2": "Apt 214",