Read and update a Payment Transaction

Retrieve detailed information about a Payment Transaction, update reference identifiers, reauthorize when amount or shipping changes, and extend the authorization period.

8 min read

At any point in the Payment Transaction lifecycle, Partners can use the Payment Transaction API to retrieve detailed information about a Payment Transaction. Transactions can also be updated with new reference identifiers, or reauthorized when the amount, line items, or shipping details change — as long as the Payment Transaction has not expired, completed, or closed.

Read Payment Transaction

Call readPaymentTransaction API

to retrieve the essential details of a Payment Transaction, including the payment amount, currency, line items, customer, shipping, pricing information, and current state.

Recommended for integration

Call readPaymentTransaction API

only when strictly required by Partners' business logic (for example, when working with non-guaranteed payments). Avoid using the read action 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.

Non-guaranteed transactions

The majority of payment solutions presented by Klarna are guaranteed, meaning Klarna ensures that payment will be made to the Partner regardless of the customer's actions, provided the Partner adheres to Klarna's terms and conditions. Klarna assumes much of the customer risk inherent in the transaction.

Non-guaranteed payments are transactions where the risk falls to the Partner if the customer fails to pay. Klarna does not cover the Partner for any losses due to non-payment by the customer. These are indicated in the payment_funding.type field. For transactions where the returned type is NON_GUARANTEED, the payment_funding object, returned alongside the Payment Transaction details, becomes relevant.

JSON

1 2 3 4

"payment_funding": {
  "type": "GUARANTEED | NON_GUARANTEED",
  "state": "PENDING | FUNDED | EXPIRED"
}

This object communicates the funding status for transactions where the risk profile falls outside of Klarna's guaranteed payment.

The possible payment_funding.state values and the expected actions are described below:

State	Definition	Expected action
`PENDING`	The customer has completed the authorization flow, but the funds have not yet been confirmed by Klarna.	The Payment Transaction is not funded. Withhold fulfillment until the state transitions to `FUNDED`. Any transaction fulfilled while in this state may be subject to chargeback if Klarna is unable to retrieve funds from the customer.
`FUNDED`	The customer has covered the debt toward Klarna and Klarna has confirmed the funds. The transaction can be considered "paid".	Capture the Payment Transaction on fulfillment to the customer.
`EXPIRED`	Klarna has not received the customer's funds for a non-guaranteed Payment Transaction after a specific period of time (which varies depending on the selected payment method).	Stop or cancel the fulfillment of this Payment Transaction.

Partners are informed about the transition from PENDING to FUNDED, as well as the transition from PENDING to EXPIRED, via payment.funding.state-change.funded and payment.funding.state-change.expired webhook events. Subscribe to them by following the webhook registration guide.

Sample payload for payment.funding.state-change.funded:

JSON

1 2 3 4 5 6 7 8 9 10

{
  "metadata": {
    "event_type": "payment.funding.state-change.funded",
    "event_id": "7f1ff389-7792-4cc5-8ec5-cb2ed6e1f19c",
    "event_version": "v2",
    "occurred_at": "2024-01-12T13: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",
    "live": true

Read Payment Chargeback

Call readPaymentChargeback API

to retrieve the details of a payment chargeback. A payment chargeback encapsulates crucial details such as the chargeback amount and the chargeback reason, which explains why Klarna decided to reverse the transaction.

The possible values for chargeback_reason are:

DISPUTE_ARBITRATION_LOST: The payment dispute has been finalized in favor of the customer, resulting in a payment chargeback being initiated.
CUSTOMER_PAYMENT_DEFAULT: For non-guaranteed offerings, if Klarna is unable to retrieve funds from the customer and prior captures had been performed, Klarna registers a chargeback for the capture total, reflected in the Partner's settlement balance. To avoid chargebacks for non-guaranteed transactions, capture only when payment is funded by the customer.

Chargeback information access

Chargeback information is also accessible through readPaymentTransaction API

. Use readPaymentChargeback API

when only the chargeback details are needed.

Whenever a dispute arbitration rules in favor of the customer, or a non-guaranteed payment defaults, Klarna triggers the payment.transaction.chargeback webhook event. Subscribe to it by following the webhook registration guide.

Update Payment Transaction

Call updatePaymentTransaction API

to change the payment_transaction_reference or the purchase_reference:

purchase_reference stores the customer-facing transaction identifier, displayed in the Klarna app and other customer touchpoints.
payment_transaction_reference stores the transaction identifier created on the Partner's side, exposed in Payment Transaction webhooks for correlating Partners' records with the Klarna Payment Transaction.

These fields are essential for aligning Partners' internal records with Klarna's transaction records and ensuring accurate tracking and reconciliation.

Reauthorize Payment Transaction

Call reauthorizePaymentTransaction API

when the amount, line_items, or shipping details of a Payment Transaction change after the original authorization. Reauthorization can also be used to extend the authorization period before it expires.

Additional payment context

Send additional data points when reauthorizing transactions by using klarna_network_data to ensure consistent customer and transaction context throughout the payment flow.

Reauthorize with a new amount or line items

Reauthorize when the amount or line_items change.

This action may only be performed:

Before the Payment Transaction expires.
If the Payment Transaction has expired but is still within the 7-day grace period. The authorization period can be extended to reauthorize with a new amount.
Before the Payment Transaction is fully captured.

Integration requirement

Lowering the authorization amount does not trigger a risk assessment.
Reauthorizing with a higher amount or new line items does trigger a second fraud assessment, which may be rejected.
This action may not be performed more than 200 times. Exceeding this limit causes the reauthorization to be rejected. See Limitations for the full action limits.

Reauthorize with new shipping details

Reauthorize when the shipping information changes. Reauthorizing with updated shipping details is essential because:

Fraud assessment: Performing a second fraud assessment with the new shipping information helps identify and mitigate potential fraudulent activities, securing the transaction.
Disputes: Maintaining accurate and updated shipping information supports dispute resolution by providing clear and documented proof of the shipping details, which can be referenced to resolve any issues.

Integration requirement

This action triggers a second fraud assessment, which may be rejected.
This action may not be performed more than 200 times. Exceeding this limit causes the reauthorization to be rejected. See Limitations for the full action limits.

Extend the authorization period

Extend the authorization when the existing authorization is nearing expiration and the payment cannot be completed within the current period. This ensures there is enough time to finalize the Payment Transaction without complications.

Integration requirement

By default, a Payment Transaction is considered CLOSED 7 days after its expiration and cannot be reauthorized after that, unless otherwise agreed with Klarna.
This action triggers a second fraud assessment, which may be rejected.
This action may not be performed more than 200 times. Exceeding this limit causes the reauthorization to be rejected. See Limitations for the full action limits.

When extending the authorization period, specify the number of days using the extension_days parameter, with a maximum extension of 180 days. The total authorization period for a Payment Transaction cannot exceed 360 days from its creation date. Any attempt to extend beyond this limit will be rejected.

Webhooks

Whenever a Payment Transaction is updated (for example, when the amount, line items, or shipping details change after reauthorization), Klarna emits the payment.transaction.updated webhook event. Subscribe to it by following the webhook registration guide.

Event name	When
`payment.transaction.updated`	The Payment Transaction has been updated, for example after a reauthorization that changes amount, line items, or shipping details.
`payment.transaction.chargeback`	A payment chargeback has been created, either due to a dispute arbitration lost or a non-guaranteed payment default.
`payment.funding.state-change.funded`	A non-guaranteed Payment Transaction has transitioned to `FUNDED`. Funds have been confirmed by Klarna and the transaction can be safely captured.
`payment.funding.state-change.expired`	A non-guaranteed Payment Transaction has transitioned to `EXPIRED`. Klarna has not received the customer's funds and fulfillment should be stopped.

Set up your webhooks

Payment Transaction state definitions

Jump to section...