Payment Transaction state definitions

Understand the lifecycle of a Payment Transaction with Klarna: its states, transitions, and the webhook events that signal each change. Use this reference when planning capture, refund, void, and reconciliation flows.

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

Overview

A Payment Transaction transitions through various states during its full lifecycle. Each state represents a specific phase in the payment process, dictating what actions can be taken and what limitations apply. Below is an overview of the possible Payment Transaction states, together with a state transition diagram.

States

State	Definition
`AUTHORIZED`	Represents a Payment Transaction that has an authorized amount remaining to be captured. It is awaiting further actions such as capture, update, or void. Refunds are also possible if the transaction has been partially captured.
`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 `CLOSED` 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 actions, including refunds, can be completed. A Payment Transaction transitions to `CLOSED` in any of the following cases: Expired before completion: the transaction is closed 7 days after expiry. Completed transaction ages out: a completed Payment Transaction transitions to closed 3 years after completion. Non-guaranteed payment defaults: a non-guaranteed Payment Transaction transitions to closed when Klarna has not received the customer's funds within a specific period of time (which varies depending on the selected payment method).

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 diagram above:

raa = remaining_authorization_amount
oaa = original_authorization_amount

Webhook events

The lifecycle of a Payment Transaction involves a sequence of events from authorization through to conclusion. The table below describes the state-change events emitted by Klarna webhooks. Subscribe to them by following the webhook registration guide.

Event name	When
`payment.transaction.state-change.authorized`	A Payment Transaction has an authorized amount remaining and is awaiting further actions like capture, update, or void. Refunds are also possible if the transaction has been partially captured.
`payment.transaction.state-change.completed`	A Payment Transaction has been finalized through funds transfer and no authorized amount remains.
`payment.transaction.state-change.expired`	A Payment Transaction has reached its lifespan without being completed. By default, an expired Payment Transaction transitions to `CLOSED` if it is not reauthorized within 7 days after expiry, unless otherwise agreed by Klarna.
`payment.transaction.state-change.closed`	A Payment Transaction has reached a definitive conclusion. No further actions, including refunds, can occur.

The example below shows the payload structure for payment.transaction.state-change.authorized:

JSON

1 2 3 4 5 6 7 8 9 10

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

For the full event payload structure, refer to the Payment Transaction API reference API

Considerations for Payment Transaction management

Limitations

All actions that modify 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.

readPaymentTransaction API

is excluded from these restrictions.

Exceeding these limits will result in a 403 response.

Read Payment Transaction

Call readPaymentTransaction API

only when strictly required by Partners' business logic (for example, when working with non-guaranteed payments). Avoid using it to confirm that a Payment Transaction was created or that another action succeeded. Each action's response is authoritative: when it returns a successful response, the action completed successfully.

Set up your webhooks

API & SDK references

Klarna Product Api Payment