As explained in the previous section, whenever a step-up scenario is triggered:

1. The customer accepts the payment: The customer enters Klarna Purchase Journey to complete authentication and accept the payment
2. The customer returns to your platform: Upon completion, Klarna redirects the customer to the provided return_url.
3. Klarna notifies Acquiring Partner of payment completion
   
   • The payment request transitions to state = COMPLETED.
   
   • Klarna issues a payment_token, required to create the transaction
   

This guide outlines how to monitor the Klarna Payment Request as part of the step up scenario and how to retrieve the payment_token required to finalize the payment.

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:

Klarna supports three integration methods. Acquiring Partners should implement at least Klarna webhook events and optionally combine it with other methods for resilience.

Acquiring Partners can subscribe to the payment.request.state-change webhooks events using the guidelines here. Klarna will send webhook notifications whenever the payment request state is updated.

The webhook event payment.request.state-change.completed is triggered when the Payment Request reaches the state COMPLETED and the webhook body will contain the payment_token.

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.

Acquiring Partners must monitor Klarna webhooks to capture the payment_token and complete the authorization flow. This ensures robustness, especially if:

• The customer closes the browser before returning
• Network issues interrupt the redirect
• There’s a need for post-processing before informing the customer

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.

This is particularly relevant whenever acquiring Partners make use of an internal return_url rather than the Partner's frontend URL when calling the Payment Authorize API.

Details about the available return_url placeholders are provided below:

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

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

• 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.

Example

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

The payment_token can also be retrieved through the Read Payment Request API. It will be stored in the state_context object of the payment request once in state = COMPLETED.

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.

Use this as a fallback or verification method together with the return_url placeholders redirect or webhooks.

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

• Subscribe to payment.request.state-change webhook events to monitor payment request created as part of the step-up scenario
• Proactively cancel payment requests which have not resulted in successful transactions
• Leverage available dynamic placeholders when making use of an internal return_url
• Handle COMPLETED, CANCELED, and EXPIRED states properly.
• Validate all returned parameters before processing payments.