Partner initiated Payment Authorization

Integrate Klarna's Payment Authorize API for server-side, partner-initiated scenarios. This guide shows how to authorize payment transactions without customer interaction, using stored customer tokens for recurring or scheduled payments.

149 min read

Authorize a Payment Transaction with Klarna using a server-side integration when the customer is not present. As an Acquiring Partner, you'll collect payment context from the Partner, call authorizePayment API

with a stored customer token, handle authorization outcomes, and return results — all without requiring customer interaction. This flow is ideal for subscription renewals, scheduled payments, and other Partner-initiated transactions.

Prerequisites

Before starting, ensure the following:

A valid Partner Account with API credentials
A valid Customer Token obtained through Payment Tokenization
Backend capability to store and manage customer tokens securely
Payment context and transaction details ready for authorization

Integration overview

Once the Partner initiates Payment Authorization (for example, a subscription renewal):

1.
The Partner initiates Payment Authorization through the Acquiring Partner's internal customer token identifier and payment details
2.
The Acquiring Partner forwards the payment context to Klarna by calling authorizePayment with the customer token
3.
Klarna evaluates the request and returns one of the following results:
- 3.1.
  APPROVED
- 3.2.
  DECLINED
4.
The Acquiring Partner handles the result and returns the outcome to the Partner

sequenceDiagram autonumber participant P as Partner participant AP as Acquiring Partner participant K as Klarna Note over P: Scheduled payment trigger (e.g., subscription renewal) P->>AP: Initiate Payment Authorization Note over P,AP: customer_reference, amount, currency, supplementary_purchase_data AP->>K: POST /payment/authorize Note over AP,K: Klarna-Customer-Token header with payment context K->>AP: Authorization result Note over K,AP: APPROVED or DECLINED AP->>P: Return authorization outcome Note over AP,P: Success or failure indicator

Integration details

Partners can initiate token charges in two ways:

Direct Klarna integration: Partners with their own Klarna integration use a Customer Token to initiate the charge and provide the resulting Klarna Network Session Token to the Acquiring Partner
Using Acquiring Partner's token: Partners use the Acquiring Partner's internal customer token identifier, which the Acquiring Partner maps to the corresponding Klarna Customer Token Update the Partner-facing API to collect the following data points from the Partner for partner-initiated payment scenarios:

Parameter	Required (Acquiring Partner)	Required (Partner)	Description
`amount`	Yes	Yes	Total amount of the authorization, including tax and any available discounts.
`currency`	Yes	Yes	Currency in ISO 4217 format.
Acquiring Partner's internal customer token identifier	Yes	Yes	The customer token identifier provided to the Partner by the Acquiring Partner during tokenization. The Acquiring Partner uses this identifier to look up the corresponding Klarna Customer Token.
`supplementary_purchase_data`	Yes	Recommended	Additional details about the transaction to help reduce fraud risk and enhance transparency. Include this data to improve underwriting, fraud detection, and customer communication. Klarna processes and uses this data for fraud assessment and customer experience optimization.
`supplementary_purchase_data.purchase_reference`	Yes	Recommended	Customer-facing payment reference displayed to customers on the Klarna app and other communications. Also included in settlement reports for reconciliation purposes. If you are an Acquiring Partner, this is the reference your Partner generated for their customer payment.
`supplementary_purchase_data.line_items`	Yes	Recommended	Detailed line item information of the purchase. Sending complete line item data is highly recommended as it improves authorization approval rates and customer experience.
`supplementary_purchase_data.customer`	Yes	Recommended	Information about the customer based on their previous interactions with the Partner. These data points may be used by Klarna to simplify sign-up and during fraud assessment, as well as for underwriting purposes to provide an enhanced experience to returning customers.
`supplementary_purchase_data.shipping`	Yes	Recommended	Shipping information for the purchase. This data is used for fraud detection and customer communication. If the purchase contains multiple shipments with different recipients, provide one shipping object per shipment.
`supplementary_purchase_data.subscriptions`	Yes	Conditional	Subscription details including subscription reference, billing plans, and free trial status. Mandatory when charging specific subscriptions.
`klarna_network_session_token`	Yes	Conditional	Encodes Klarna Network session context (prequalification, sign-in state, or approval). Optional for partner-initiated flows as authorization typically relies on stored customer tokens via `customer_reference`.
`klarna_network_data`	Yes	Recommended	Additional data to enable custom features or data exchange supported by your Integrating Partner. Klarna accepts this passthrough field in a structured JSON format and forwards it to relevant systems for interoperability. Data shared in this field may complement structured datapoints provided in supplementary_purchase_data. Treat this value as an opaque string; do not validate or infer its structure.

Requirements

Use exact parameter names klarna_network_session_token and klarna_network_data in the Partner-facing API to ensure Partners can easily identify and use them.
Forward all parameters unmodified to Klarna.
Parameter validation must not be more restrictive than Klarna's authorizePayment.
Support all printable UTF-8 characters.
Supplementary purchase data handling:
- Map your existing Partner-facing fields (line items, customer billing address, shipping, purchase reference) into supplementary_purchase_data when calling Klarna
- Don't add new Partner-facing fields "just for Klarna" if you already have equivalent fields in your existing schema. Avoid forcing Partners to submit the same data twice using parallel structures

Do	Don't
Map existing line items into `supplementary_purchase_data.line_items`.	Introduce a parallel line-item structure such as `klarna_line_items`.
Map existing customer details into `supplementary_purchase_data.customer`.	Duplicate customer fields you already collect from Partners.
Map existing shipping data into `supplementary_purchase_data.shipping`.	Add a separate shipping object "just for Klarna".
Map your existing purchase reference into `supplementary_purchase_data.purchase_reference`.	Force Partners to submit the same purchase reference twice.

Supplementary purchase data scenarios

Acquiring Partners may receive supplementary purchase data (including line items, L2/L3 data for Card Network optimization, and transaction context) in one or both of the following ways:

Embedded in klarna_network_data: Forward as received without parsing or mapping
Provided as individual API fields: Map to the supplementary_purchase_data object when calling authorizePayment

flowchart LR Partner[Partner]:::tertiaryEntity LineItems[Line items,\nL2/L3 data,\netc]:::secondaryEntity KlarnaNetLeft[Klarna Network Data]:::secondaryEntity AP[Acquiring Partner's API]:::primaryEntity Supplementary[Supplementary\nPurchase Data]:::secondaryEntity KlarnaNetRight[Klarna Network Data]:::secondaryEntity Auth[Payment Authorization]:::primaryEntity %% Main flows Partner --> LineItems --> AP --> Supplementary --> Auth Partner --> KlarnaNetLeft --> AP --> KlarnaNetRight --> Auth

The authorizePayment API

API is used to start the payment process on Klarna whether they are with or without customer presence.

In the request to authorizePayment API

, specify the following parameters:

SHELL

1 2 3 4 5 6 7 8 9 10

curl https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/payment/authorize \
  -H 'Authorization: Basic <API key>' \
  -H 'Klarna-Customer-Token: <token>' \
  -H 'Klarna-Network-Session-Token: <token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "currency": "USD",
        "request_payment_transaction": {
          "amount": 11800,
          "payment_option_id": "***",

When performing Partner-initiated authorization through authorizePayment API

, Klarna returns a response that reflects the result of the authorization. Since this flow includes a request_payment_transaction in the request and the customer is not present, the response will always contain a payment_transaction_response object with a result field that indicates the outcome.

For partner-initiated flows without customer interaction, the result has the following possible values:

Result	Description	Next steps
`APPROVED`	The authorization succeeded and a `payment_transaction` was created.	Store the `payment_transaction_id`, return success to Partner, and proceed with post-purchase operations (capture or refund) as needed.
`DECLINED`	The authorization failed (for example, due to fraud, credit, or risk policy) and no transaction was created.	Return failure response to Partner and end the authorization flow.

No step-up support

Partner-initiated payments do not support the STEP_UP_REQUIRED result since the customer is not present to complete additional verification.

The response schema is as follows:

Sample response

Authorization response approved

1 2 3 4 5 6 7 8 9 10

{
  "payment_transaction_response": {
    "result": "APPROVED",
    "payment_transaction": {
      "payment_transaction_id": "krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0",
      "payment_transaction_reference": "partner-transaction-reference-1234",
      "amount": 1000,
      "currency": "USD",
      "state": "COMPLETED",
      "payment_pricing": {