Subscriptions and on-demand

Learn more about the use cases:

• Subscriptions: allows customers to sign up for a subscription using Klarna as their payment method.. Once complete, the payment preferences are tokenized and automatically used for renewals by the merchant using the token to create orders. Shoppers can manage their preferences at any time in the Klarna App.
• On-demand: allows customers to add Klarna as a payment method in a digital wallet for one-click purchases of on-demand services. Shoppers can update their payment preferences at any time in the Klarna App.

Both use cases are facilitated by the "customer token".

A customer token is the combination of customer details and payment method data, together with a connection to a specific merchant.

A customer token helps speed up the checkout process. You only have to collect a customer's details and payment method information once to be able to reuse it for recurring orders. The customer doesn't need to take action as you can create orders on their behalf.

When you create an order using a customer token, we run a risk and fraud assessment to ensure that the customer can be offered credit for the order amount.

Customer tokens are stored in Klarna’s internal secure databases and no private information linked to customer tokens is shared externally.

You can create a customer token by sending a request through Klarna payments API.

A customer token can be either active, suspended, or canceled. When a token is created, its status is set to active by default.

You can use the Klarna payments API to perform three actions related to a customer token:

1. Create an order in a payment session with intent set to tokenize or buy_and_tokenize.
2. Check the details of a customer token.
3. Cancel a customer token.

A customer token doesn't have an expiration date. It stays active until you cancel it.

Once you know that you'll not use a customer token anymore, for example, if your customer unsubscribes from your service or deletes their account, you can cancel a customer token using the Klarna payments API.

To check the status of a customer token, send a request using the Klarna payments API.

Yes, you can share a customer token between multiple Merchant IDs (MIDs) used by your company (for example, one MID dedicated to customer signup and another for placing orders). This is known as token clustering.

Initially, we assign a new customer token to the MID you got when you were onboarded to Klarna. If you want to link a customer token to other MIDs, contact Merchant support.

If you're using customer tokens in your checkout, you need to:

1. Inform your customers of how you'll use the customer token for recurring purchases.
2. Store customer tokens securely.
3. Map your customers to customer tokens. Be able to correctly map your customer to our customer token ID.
4. Trigger purchases from a customer token.

The information related to subscriptions is included in the subscription object inside the request's order_lines . This information lets us make better underwriting decisions and present the most fitting payment options (for example, monthly subscriptions vs. annual).

This object plays a key role in the post-purchase display of automatic payments in the Klarna app.  

Technical considerations:

• Klarna doesn’t manage, maintain or validate uniqueness of the data points sent, meaning that any subscription name sent will be accepted, regardless of it existing on your side.
• You have to include the subscription object in requests related to subscriptions whenever order lines are shared, that is, in the token creation flow (create session, load(), authorize(), and create order calls), and when you're creating an order using a customer token.
• When using delayed captures in the Order management API, you have to include the subscription object when overriding order lines.
• You are responsible for setting the logic of when new orders should be created using customer tokens. For example, if you're using customer tokens to charge your customers for recurring purchases, such as subscriptions, you have to create orders at intervals you specified when setting up the recurring payment order.

The subscription object contains the following elements:  

For example, if you want to charge for a subscription once a quarterly, set the value of interval to "MONTH" and interval_count to 3 . For a charge happening annually, set interval to "YEAR" and interval_count to 1 .

A customer subscribed to a monthly streaming subscription for 15.99/month with a free 14-day trial.

Initiate a payment

POST /payments/v1/sessions 
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA== 
Content-Type: application/json 
{ 
  "intent": "tokenize",
  "purchase_country": "DE", 
  "purchase_currency": "EUR", 
  "locale": "de-DE", 
  "order_amount": 0, 
  "order_tax_amount": 0, 

Create a customer token

POST /customer-token/v1/tokens/{customerToken}/order 
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA== 
Klarna-Idempotency-Key: b19f321c-8f38-11ec-b909-0242ac120002
Content-Type: application/json 
{ 
  "auto_capture": true,
  "purchase_country": "DE", 
  "purchase_currency": "EUR", 
  "locale": "de-DE",
  "merchant_reference1": "123456",

A customer subscribed to regularly receive 2 different products at different time intervals: Ink cartridges every month and deodorant creme every 2 months.

Create a Klarna payments session for multiple subscription items

POST /payments/v1/sessions 
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA== 
Content-Type: application/json 
{ 
  "intent": "buy_and_tokenize",
  "purchase_country": "DE", 
  "purchase_currency": "EUR", 
  "locale": "de-DE", 
  "billing_address": {
       	"given_name": "Thomas",

Create an order and complete the first purchase at checkout

POST /payments/v1/authorizations/<authorization_token>/order
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json
{
  "purchase_country": "DE",
  "purchase_currency": "EUR",
  "billing_address": {
       	"given_name": "Thomas",
       	"family_name": "Testkunde",
       	"email": "thomas.testkunde@gmail.com",

Create an order using a customer token (month 1)

POST /customer-token/v1/tokens/{customerToken}/order 
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA== 
Klarna-Idempotency-Key: b19f321c-8f38-11ec-b909-0242ac122202
Content-Type: application/json 
{ 
  "auto_capture": true,
  "purchase_country": "DE", 
  "purchase_currency": "EUR", 
  "locale": "de-DE",
  "merchant_reference1": "123456",

Create an order using a customer token (month 2)

POST /customer-token/v1/tokens/{customerToken}/order 
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA== 
Klarna-Idempotency-Key: b19f321c-8f38-11ec-b909-0242ac121102
Content-Type: application/json 
{ 
  "auto_capture": true,
  "purchase_country": "DE", 
  "purchase_currency": "EUR", 
  "locale": "de-DE",
  "merchant_reference1": "123456",

Capture a request

POST /ordermanagement/v1/orders/{order_id}/captures
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json
{
  "captured_amount": 999,
  "reference": "12345678", 
  "order_lines": [{ 
        "type": "digital", 
        "subscription": { 
        	"name": " Premium Monthly {{1234834}}",