Manage payment transactions with Klarna Network

Manage Payment Transactions efficiently with Klarna by understanding transaction states, event tracking, and operational limits for seamless processing.

The Payment Transaction API allows Klarna’s Partners to track the lifecycle of a payment transaction and perform all post-purchase operations including transaction updates, captures, and refunds.

Payment transaction state definitions

The payment transaction will transition to various states during its full lifecycle, with each state representing a specific phase in the payment process dictating what actions can be taken and what limitations are in place. Below you will find an overview of the possible payment transaction states together with a state transition diagram.

State	Definition
`AUTHORIZED`	Represents a payment transaction that has an authorized amount remaining to be captured. It is awaiting further actions such as capture, refund, update, or void.
`EXPIRED`	Represents a payment transaction that has reached its lifespan without being completed. A transaction expires if it is not fully captured within a set period of time. By default, an expired payment transaction transitions to the `CLOSED` state if it is not reauthorized within 7 days after the expiry unless otherwise agreed by Klarna.
`COMPLETED`	Represents a payment transaction that has been finalized through a funds transfer. A payment transaction is considered completed when no authorized amount remains, either because it is fully captured or was partially captured and has since expired. Fully captured: The funds corresponding to the full authorization amount have been successfully captured. Partially captured and expired: The payment transaction has been partially captured, and the 7-day grace period has passed upon expiration. Any remaining authorization is released, and the payment authorization is considered to be completed.
`CLOSED`	Represents a payment transaction that has reached its definitive conclusion, or end of life. In this state, no further operations, including refunds, can be completed. A payment transaction that expires before completion is deemed closed 7 days after expiry. A completed payment transaction transitions to closed after 3 years. Upon closure, no refunds can take place. A non-guaranteed payment transaction transitions to closed when not receiving the customer’s funds after a specific period of time (which varies on the selected payment option).

flowchart LR Start((Start)):::teritiaryEntity --> AUTHORIZED1[AUTHORIZED]:::secondaryEntity CapturedBridge{ }:::teritiaryEntity ExpiredBridge{ }:::teritiaryEntity %% ----------------------------- %% Created Transaction %% ----------------------------- subgraph Created_Transaction [Created transaction] direction TB AUTHORIZED1 --> Decision1{ }:::teritiaryEntity Decision1 -->|"full capture (raa = 0)"| COMPLETED_FULLY_CAPTURED[COMPLETED]:::primaryEntity Decision1 -->|"partial capture with RELEASE (raa = 0)"| COMPLETED_FINAL_CAPTURED[COMPLETED]:::primaryEntity Decision1 -->|"void (raa ≠ oaa)"| COMPLETED_VOIDED[COMPLETED]:::primaryEntity Decision1 -->|"partial capture w/o RELEASE (raa > 0)"| AUTHORIZED2[AUTHORIZED]:::secondaryEntity Decision1 -->|reauthorize| AUTHORIZED3[AUTHORIZED]:::secondaryEntity Decision1 -->|"refund or chargeback (raa ≠ oaa)"| AUTHORIZED4[AUTHORIZED]:::secondaryEntity Decision1 -->|"t > expires_at"| EXPIRED1[EXPIRED]:::teritiaryEntity Decision1 -->|Customer payment default| CLOSED1[CLOSED]:::primaryEntity Decision1 -->|"void (raa = oaa)"| CLOSED2[CLOSED]:::primaryEntity COMPLETED_FULLY_CAPTURED --> CapturedBridge COMPLETED_FINAL_CAPTURED --> CapturedBridge COMPLETED_VOIDED --> CapturedBridge EXPIRED1 --> ExpiredBridge end %% ----------------------------- %% Expired Transaction %% ----------------------------- subgraph Expired_Transaction [Expired transaction] direction TB ExpiredBridge --> Decision3{ }:::teritiaryEntity Decision3 -->|"reauthorize t < (expires_at + 7 days)"| AUTHORIZED5[AUTHORIZED]:::secondaryEntity Decision3 -->|"t > (expires_at + 7 days) raa ≠ oaa"| COMPLETED4[COMPLETED]:::primaryEntity Decision3 -->|"t > (expires_at + 7 days) raa = oaa"| CLOSED3[CLOSED]:::primaryEntity COMPLETED4 -->|t > 3 years| CLOSED4[CLOSED]:::primaryEntity end %% ----------------------------- %% Captured Transaction %% ----------------------------- subgraph Captured_Transaction [Captured transaction] direction TB CapturedBridge --> Decision2{ }:::teritiaryEntity Decision2 -->|Customer payment default| CLOSED5[CLOSED]:::primaryEntity Decision2 -->|"t > 3 years"| CLOSED6[CLOSED]:::primaryEntity Decision2 -->|refund or chargeback| COMPLETED5[COMPLETED]:::primaryEntity COMPLETED5 -->|t > 3 years| CLOSED6 end

The following acronyms are used in the above diagram:

raa = remaining_authorization_amount
oaa = original_authorization_amount

The lifecycle of a payment transaction involves a sequence of events from authorization through to conclusion. Below is a table describing the events supported by Klarna webhooks for payment transaction state change.

Event name	When
`payment.transaction.state-change.authorized`	To track when a payment transaction has an authorized amount remaining and is awaiting further actions like capture, refund, cancel.
`payment.transaction.state-change.completed`	To track when a payment transaction has been finalized through funds transfer and no authorized amount remains.
`payment.transaction.state-change.expired`	To track when a payment transaction reaches its lifespan without being completed. A transaction expires if it is not fully captured within a set period of time. By default, an expired payment transaction transitions to the `CLOSED` state if it is not reauthorized within 7 days after the expiry unless otherwise agreed by Klarna. v
`payment.transaction.state-change.closed`	To track when a payment transaction reaches a definitive conclusion, where no further operations, including refunds, can occur.

The following example reflects the payload structure for payment.transaction.state-change.authorized:

JSON

{
  "metadata": {
    "event_type": "payment.transaction.state-change.authorized",
    "event_id": "7f1ff389-7792-4cc5-8ec5-cb2ed6e1f19c",
    "event_version": "v2",
    "occurred_at": "2024-01-01T13: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-a2c1-103dba3fc918",
    "webhook_id": "krn:partner:global:notification:webhook:120e5b7e-abcd-4def-8a90-dca726e639b5",
    "live": true

Consult the API reference Klarna Icon for a complete description of the request body parameters.

Limitations to payment transaction management

All operations that perform an action on a payment transaction are limited, and can only be performed 200 times each. The total number of actions performed on a given payment transaction may not exceed 500 operations.

readPaymentTransaction Klarna Icon is excluded from these restrictions.

Exceeding these limitations will result in a 403 response.