Klarna Docs - Manage payment transactions with Klarna Network

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

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

Consult the API reference 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.

Read Payment Transaction is excluded from these restrictions.

Exceeding these limitations will result in a 403 response.