Klarna Docs - Set up a recurring payment order.

Set up a recurring payment order.

Once Klarna authorizes the purchase, it's time to create an order and complete the payment.

For recurring payments, you have to create a customer token before placing the order. This token identifies your customer and the payment method selected for the purchase. It also lets you charge the customer later, ad-hoc or at regular intervals.

For payments where you charge the customer at checkout and enable a recurring charge (intent set to buy_and_tokenize), you have to send two separate create order requests:

  1. In the first request, use authorization_token to charge the customer at checkout.
  2. In the second request, use cutomer_token for future recurring payments.

If you're not charging the customer at checkout (intent set to tokenize), you need to send only the second request to place the order and charge the customer at a later date.

If you're creating an order related to a subscription, include the subscription object in your create order request. Learn more about sharing subscription details with Klarna.

Learn more about customer tokens.

Requesting a token.

Request a customer token by sending a POST request to the {apiUrl}/payments/v1/authorizations/{authorizationToken}/customer-token endpoint.

Include the authorization token from the authorize() call as the authorizationToken path parameter.

JSON
{
    "purchase_country": "US",
    "locale": "us-US",
    "billing_address" : {
        "given_name": "Doe",
        "family_name": "John",
        "email": "john@doe.com",
        "phone": "333444555",
        "street_address": "Lombard St 10",
        "postal_code": "90210",

A POST request to create a customer token for a customer located in the US.

Success response.

In response to the customer token request, Klarna sends:

  • token_id, a customer token identifier that you later use to create an order
  • redirect_url, a URL to which the customer is redirected after the order is placed
JSON
{
    "billing_address": {
        "city": "Beverly Hills",
        "country": "US",
        "email": "john@doe.com",
        "family_name": "Doe",
        "given_name": "John",
        "phone": "333444555",
        "postal_code": "90210",
        "region": "CA",

A success response contains a customer token (token_id).

Error response.

If Klarna can't create a customer token based on the data you sent, you'll receive an error response.

JSON
{
    "correlation_id": "6a9b1cb1-73a3-4936-a030-481ba4bb203b",
    "error_code": "ERROR_CODE",
    "error_messages": [
        "ERROR_MESSAGE"
    ]
}

An error response to a create a customer token request.

Here are examples of common errors with troubleshooting suggestions. You can use the value in correlation_id to find entries related to the request under Logs in the Merchant portal.

Error codeError messageDescription
NOT_FOUNDInvalid authorization tokenThe authorization token has expired. Make sure to place within 60 minutes of authorization or re-authorize the purchase.
BAD_VALUEBad value: purchase_countryThe billing address country is different from that of the country specified for this session.
BAD_REQUESTX is not valid for creating customer tokens in YThe selected payment method can't be tokenized in the specified country.
INVALID_OPERATIONNot allowed to create customer tokens for intent buy.You can only create a token when the intent of the session is set to tokenize or buy_and_tokenize. Learn more about intent.

This section only applies to payment sessions where intent: buy_and_tokenize. For payments with intent: tokenize, create an order with a customer token.

Creating an order.

To charge the customer at checkout, send a POST request to the {apiUrl}/payments/v1/authorizations/{authorizationToken}/order endpoint. Include the authorization token as a path parameter.

For example, if the authorization_token is b4bd3423-24e3, send your request to the {apiUrl}/payments/v1/authorizations/b4bd3423-24e3/order endpoint.

Include subscription details in the subscription object. These should match the details you previously shared with Klarna when initiating the payment session.

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

A create order request for a subscription where a customer is charged once a month.

Success response.

In response to a create order call, you receive:

  • order_id, an order identifier that you can later use to capture or refund the order using the Order management API
  • redirect_url, a URL to which you redirect the customer. This isn't included in the response received if you didn't include the URL when initiating a payment
  • fraud_status, an indicator of whether the transaction is suspected to be fraudulent
  • authorized_payment_method, the payment method selected by your customer for this purchase
JSON
{
    "order_id": "3eaeb557-5e30-47f8-b840-b8d987f5945d",
    "redirect_url": "https://payments.klarna.com/redirect/...",
    "fraud_status": "ACCEPTED",
    "authorized_payment_method": "invoice"
}

A success response to a place order request created with an authorization token.

Error response.

If your request doesn't pass our validation, you'll receive an error response. The most common reasons why creating an order fails are:

  • placing the order more than 60 minutes after authorization
  • modifying purchase details after authorization without updating the payment session
JSON
  {
      "correlation_id": "6a9b1cb1-73a3-4936-a030-481ba4bb203b",
      "error_code": "ERROR_CODE",
      "error_messages": [
          "ERROR_MESSAGE"
      ]
  }

An error response to the order creation request for a recurring payment based on authorization_token.

Here are examples of common errors with troubleshooting suggestions. You can use the value in correlation_id to find entries related to the request under Logs in the Merchant portal.

Error codeError messageDescription
NOT_FOUNDInvalid authorization tokenThe authorization token has expired because the order was placed more than 60 minutes after authorization. To fix the error, request a new authorization_token and use it to place the order.
BAD_VALUENot matching fields: [billing_address.postal_code]The data shared with Klarna in a previous step (create_session, load, or authorize) have been modified causing the validation to fail.
BAD_VALUENot matching fields: [Incorrect number of items in the cart. Expected: 2, Actual: 3]The order lines or the cart were updated after the authorize call. Please ensure that the cart is kept as-is or send a new authorize request.
REJECTEDRejectedThis is an edge case reason, but can be triggered in case the merchant is configured with being allowed to update the cart. This could be updated from the authorize to the place order in such a way that a new authorize is triggered. In this case this is rejected.

When creating an order with a customer token, include Klarna-Idempotency-Key in the request header.

Creating an order.

Send a POST request to the {apiUrl}/customer-token/v1/tokens/{customerToken}/order endpoint and include the customer token as a path parameter.

For example, if the token_id is 0b1d9815-165e-42e2-8867-35bc03789e00, send your request to the {apiUrl}/customer-token/v1/tokens/0b1d9815-165e-42e2-8867-35bc03789e00/order endpoint.

Make sure to also include subscription details in the subscription object. These should match the details you previously shared with Klarna when initiating the payment session.

JSON
{
    "merchant_reference1": "45aa52f387871e3a210645d4",
    "merchant_data": "optional string",
    "locale": "de-DE",
    "auto_capture": true,
    "purchase_currency": "EUR",
    "order_amount": 999,
    "order_tax_amount": 0,
    "order_lines": [{
        "type": "digital",

Success response.

In response to a create order call, you receive:

  • order_id, an order identifier that you can later use to capture or refund the order using the Order management API
  • fraud_status, an indicator of whether the transaction is suspected to be fraudulent
JSON
{
    "order_id": "a89ec121-1276-419d-882a-c343d58fd1bc",
    "fraud_status": "ACCEPTED"
}

A success response to a place order request created with a customer token.

Error response.

If your request doesn't pass our validation, you'll receive an error response.

JSON
{
    "error_code" : "ERROR_CODE",
    "error_messages" : ["Array of error messages"],
    "correlation_id" : "Unique id for this request used for troubleshooting."
}

An error response to creation an order request based on a customer token.

Here are examples of common errors with troubleshooting suggestions. You can use the value in correlation_id to find entries related to the request under Logs in the Merchant portal.

Error codeHTTP status codeDescription
TOKEN_NOT_FOUND404The customer token wasn't found. Make sure that customerToken in the path matches the token.
TOKEN_SUSPENDED403The customer token has been suspended by Klarna.
TOKEN_CANCELED403You have canceled this customer token before. Create a new customer token and try again.
TOKEN_FORBIDDEN403The customer token exists, but isn't linked to your merchant ID. Try again with another customer token.
UNAVAILABLE_PAYMENT_METHOD403The payment method type is not available, for example, a card token has failed.
PAYMENT_METHOD_CURRENCY_MISMATCH403The payment method can't be used for orders in the specified currency.
PAYMENT_METHOD_FAILED403Purchase for payment method failed. If a credit payment method was used, this is most likely due to the customer being rejected. Try resending your request.
BAD_REQUEST400
INTERNAL_SERVER_ERROR500An internal server error occurred. Try again later.
SERVICE_UNAVAILABLE503A temporary internal Klarna error occurred. Try again later.