Integration overview

Once the customer selects Klarna at checkout and click on the Pay button:

1. 1.
   The Partner sends a request to the Acquiring Partner to create a Klarna payment session that contains purchase details, klarna_network_session_token and klarna_network_data.
2. 2.
   The Acquiring Partner forwards the required payment context data to Klarna’s Payment Authorization API including:

   • 2.1.
     supplementary_purchase_data
   • 2.2.
     step_up_config
   • 2.3.
     request_payment_transaction
3. 3.
   Klarna returns one of the following responses:

   • 3.1.
     STEP_UP_REQUIRED – customer needs to go through Klarna's purchase journey, either return the klarna payment_request_id or payment_request_url to the Partner.
   • 3.2.
     APPROVED – transaction is completed, proceed to confirmation and store payment_transaction_id.
   • 3.3.
     DECLINED – payment was denied, inform the Partner that the payment could not be completed, the Partner should invite the customer to select another payment method.

Before calling Klarna’s Payment Authorization API, the Acquiring Partner must ensure their backend accept and forward Klarna specific parameters. These include Klarna Network parameters that preserve session context as well as supplementary purchase data which improves Klarna’s ability to assess risk, optimize approval rates, and deliver a more personalized checkout experience.

When Partners optimize their integration with Klarna, they are likely to have Klarna Network data points to share with the Acquiring Partner. These data points enable interoperability between the Boost Features and Payment Presentation or Payment Authorization.

These ensure consistent customer and transaction context throughout the payment flow and must be forwarded unaltered to Klarna.

Enable interoperability for Payment Presentation	Enable interoperability for Payment Authorization

Implementation requirements

• Accept the Klarna Network parameters in the Partner-facing payment request API.
• Forward the Klarna Network parameters unmodified to Klarna’s Payment Authorization API.
• Validation can and should be implemented, but it must not be more restrictive than what is specified in Klarna’s Payment Authorize API. Make sure that all special characters permitted by the API specification are accepted.

Below an example of how Acquiring Partners can accept the Klarna Network parameters in their Payment request API endpoint.

Sample request

{
  "currency": "USD",
  "amount": 17800,
  "payment_method_options": {
    "klarna": {
      "klarna_network_session_token": "eyJhbGciOiJ...",
      "klarna_network_data": "{\"content_type\":\"application/vnd.klarna.interoperability-data.v2+json\",\"content\":{\"payment_request\":{...}}}"
    }
  }
}

Supplementary Purchase Data refers to additional transaction details shared with Klarna that provide greater context about a purchase. These data points—such as line items, subscription details, or industry-specific attributes—help improve underwriting accuracy, fraud assessment, and the customer’s post-purchase experience. They may be required in certain industries and support multiple use cases, including better acceptance rates, enhanced fraud prevention, improved customer experiences within the Klarna app, and more effective risk monitoring.

The Payment Authorize API is used to authorize payments on Klarna Network — whether they are one-time purchases, tokenized payments, token charges, or a final authorization following a step-up flow. All requests must include the applicable supplementary_purchase_data as defined by Klarna Network Rules.

A one-time payment represents the most common scenario, where the customer completes a single purchase with Klarna. The call may return an immediate authorization (APPROVED) or require additional customer interaction (STEP_UP_REQUIRED).

In the request to the Payment Authorize API, specify the following parameters:

curl https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/payment/authorize \
  -H 'Authorization: Basic <API key>' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Network-Session-Token: eyJhbGciOiJIU...' \
  -d '{
        "currency": "USD",
        "supplementary_purchase_data": { .. },
        "klarna_network_data": "<serialized-json>",
        "request_payment_transaction": {
          "amount": 11800,
          "payment_option_id": "***",
          "payment_transaction_reference": "acquiring-partner-transaction-reference-1234"

The response schema is as follows:

When performing a one-time payment or token charge through the Payment Authorize API, Klarna returns a response that reflects the result of the payment authorization. Because this flow only includes a request_payment_transaction in the request, the response will always contain a corresponding payment_transaction_response object. The result field inside this object indicates the outcome of the authorization and determines the next step to perform.

The result has the following possible values:

When Klarna cannot immediately create a Payment Transaction and a step_up_config was provided in the request, Klarna returns STEP_UP_REQUIRED with a payment_request. The partner must redirect the customer to Klarna’s purchase journey URL to complete authentication and payment option selection.

When the payment cannot be completed instantly, Klarna returns the payment_request details including the payment_request_id and payment_request_url which should be used to launch the Klarna Purchase Journey.

Sample payload

{
  "payment_transaction_response": {
    "result": "STEP_UP_REQUIRED"
  },
  "payment_request": {
    "payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
    "payment_request_reference": "acquiring-partner-request-reference-1234",
    "amount": 11800,
    "currency": "USD",
    "state": "SUBMITTED",
    "expires_at": "2025-01-02T13:00:00Z",
    "created_at": "2025-01-01T12:00:00Z",

When the payment authorization is approved, Klarna returns an APPROVED result and a newly created payment_transaction.

The Acquiring Partner must store the payment_transaction_id for post-purchase operations (capture, refund, etc.) through the Payment Transactions API.

An APPROVED result means the payment has been authorized successfully without requiring further customer interaction.

Sample payload

{
  "payment_transaction_response": {
    "result": "APPROVED",
    "payment_transaction": {
      "payment_transaction_id": "krn:payment:eu1:transaction:6debe89e-98c0-[...]",
      "payment_transaction_reference": "transaction-reference-1234",
      "amount": 11800,
      "currency": "USD",
      "payment_funding": {
        "type": "INVOICE",
        "details": { }
      },

If Klarna cannot approve the payment, the API returns a DECLINED result without a payment_transaction. Partners should treat this as a final rejection unless instructed by Klarna to retry.

Sample payload

{
  "payment_transaction_response": {
    "result": "DECLINED",
    "result_reason": "PAYMENT_DECLINED"
  }
}