With this integration path, the Acquiring Partner allows the customer to go through Klarna’s Purchase Journey to authenticate and approve the payment. Once the customer has completed this process:

• Klarna redirects the customer to the return_url initially provided by the Acquiring Partner in the customer interaction method parameter.
• The payment request transitions to the state = COMPLETED and Klarna issues a payment_token for the Acquiring Partner to authorize the payment.
• The Acquiring Partners listens to webhooks to monitor the payment state and retrieve the payment_token.

The payment_token returned by Klarna confirms the customer's approval for payment and is required to authorize the transaction with Klarna.

During the checkout process, the Payment Request will transition to various states. Find below an overview of the possible payment request states together with a transition diagram:

There are several ways to monitor the payment state and retrieve the payment_token:

1. Subscribing to webhook events (required)
2. Placeholders in the return_url
3. Read the Payment Request

It is important to ensure you handle errors and fail gracefully regardless of the outcome of the transaction, see Integration resilience for more information on ensuring a robust integration.

The webhook triggered when the Payment Request reaches the state COMPLETED will contain the payment_token. The content of the payload{} will slightly differ depending on the Payment Request state.

To configure webhooks for the Partner accounts please follow the guidelines here.

Sample payload

{
  "metadata": {
    "event_type": "payment.request.state-change.completed",
    "event_id": "d9f9b1a0-5b1a-4b0e-9b0a-9e9b1a0d5b1a",
    "event_version": "v2",
    "occurred_at": "2024-01-01T12:00:00Z",
    "correlation_id": "2d1557e8-17c3-466c-924a-bbc3e91c2a02",
    "subject_account_id": "krn:partner:global:account:live:HGBY07TR",
    "recipient_account_id": "krn:partner:global:account:live:LWT2XJSE",
    "product_instance_id": "krn:partner:product:payment:ad71bc48-8a07-4919-[...]",

Consult the API reference for a complete description of the webhook payload.

The return_url directs the customer back to the Partners website to the predefined url after a successful or abandoned authorization. By incorporating placeholders into the URL, Klarna can dynamically insert relevant transaction information, ensuring the URL contains all necessary details for processing.

Details about the available return_url placeholders are provided below:

Once the customer completes a payment and is redirected, the return_url will contain the payment request data points replacing the placeholders.

Sample request URL

{
  "currency": "USD",
  "supplementary_purchase_data": { .. },
  "interoperability_data":  "<serialized-json>",
  "request_payment_transaction": {
    "amount": 11800,
    "payment_transaction_reference": "acquiring-partner-transaction-reference-1234"
  },
  "step_up_config": {
    "payment_request_reference": "acquiring-partner-request-reference-1234",

Klarna adds the content requested as below, resulting in the customer being redirected as illustrated in the response.

https://acquiringpartner.example/klarna-redirect?payment_token=krn:payment:eu1:payment-token:31b543e0-6430-64df-970c-f1ae3cd9d8b0&request_id=krn:payment:eu1:request:10be1d49-7beb-6b24-b9dd-8c14d0528503&state=COMPLETED&reference=acquiring-partner-reference-12345

Parse the URL parameters to extract the Payment Request details, and pass these details to your systems accordingly. Validate that these parameters match your expectations, and the other methods through which this information is communicated.

Klarna recommends that all Partners verify data received via redirect against webhook data to prevent payment_token misuse. Payment tokens passed through the return_url are only valid for the account that completes the payment, ensuring protection against hijacking.

The payment_token can also be retrieved through the Read Payment Request API. This approach allows integrators to secure the necessary token to finalize the transaction. It is especially beneficial for verifying the token or acquiring it following the initial redirection flow. By leveraging both the return_url placeholders and the read payment request endpoint, Partners can ensure they have all the necessary tools to manage and confirm payments efficiently.

Sample response -State COMPLETED

{
  "payment_request_id": "krn:payment:eu1:request:10be1d49-7beb-6b24-b9dd-8c14d0528503",
  "state": "COMPLETED",
  "previous_state": "IN_PROGRESS",
  "state_context": {
    "payment_token": "krn:payment:eu1:payment-token:31b543e0-6430-64df-970c-f1ae3cd9d8b0"
  },
  "expires_at": "2025-02-26T17:25:34.534721775Z",
  "created_at": "2025-02-24T17:25:34.534721775Z",
  "updated_at": "2025-02-24T17:25:34.534721775Z",