Cancel a Payment Request

Learn how to cancel an existing Payment Request to prevent further processing. This operation transitions the Payment Request to the CANCELED state, which is a final state from which no further actions can be taken.

90 min read

Introduction

Cancel an existing Payment Request to prevent further processing. This operation transitions the Payment Request to the CANCELED state, which is a final state from which no further actions can be taken.

Proactive cancellation recommended

Klarna recommends proactively canceling Payment Requests that have not resulted in successful transactions, especially when the Payment Request timeout is less than 3 hours. A Payment Request remains open for 3 hours and automatically expires if not completed or explicitly canceled.

Prerequisites

Before canceling a Payment Request, ensure the following:

A valid Klarna Partner Account with API credentials
Backend capability to receive and process Klarna webhooks
The payment_request_id of an existing Payment Request in SUBMITTED, IN_PROGRESS, or COMPLETED state

Cancelable states

Payment Requests can be canceled while in SUBMITTED, IN_PROGRESS, or COMPLETED state. A COMPLETED Payment Request can be canceled only until the Payment Authorization is finalized. See Cancel a completed Payment Request. Payment Requests in EXPIRED or DECLINED state can't be canceled.

Request

Call cancelPaymentRequest API

with the payment_request_id to cancel the Payment Request. This is a DELETE operation with no request body.

Sample request

SHELL

1 2 3

curl -X DELETE https://api-global.test.klarna.com/v2/payment/requests/{payment_request_id} \
  -H 'Authorization: Basic <API key>'

Response

The API returns the canceled Payment Request with state CANCELED.

Sample response

JSON

1 2 3 4 5 6 7 8 9 10

{
  "payment_request_id": "krn:payment:eu1:request:10be1d49-7beb-6b24-b9dd-8c14d0528503",
  "state": "CANCELED",
  "expires_at": "2025-02-26T17:25:34.534721775Z",
  "created_at": "2025-02-24T17:25:34.534721775Z",
  "updated_at": "2025-02-24T17:35:00.123456789Z",
  "canceled_at": "2025-02-24T17:35:00.123456789Z",
  "payment_request_reference": "partner-request-reference-1234",
  "amount": 11836,
  "currency": "EUR",

Webhook

Subscribe to the payment.request.state-change.canceled webhook event by following the webhook registration guide. Klarna sends this event when a Payment Request is successfully canceled.

Sample payload

JSON

1 2 3 4 5 6 7 8 9 10

{
  "metadata": {
    "event_type": "payment.request.state-change.canceled",
    "event_id": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
    "event_version": "v2",
    "occurred_at": "2025-02-24T17:35:00Z",
    "correlation_id": "4f3779ga-39e5-688e-b46e-d1c5g03e4c24",
    "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-[...]",

Cancel a completed Payment Request

A Payment Request in COMPLETED state can be canceled with cancelPaymentRequest API

as long as the Payment Authorization hasn't been finalized, meaning no Payment Transaction has been created from it. This lets the Partner stop a purchase after the customer completes the Klarna Purchase Journey, for example when the Partner's own checks fail before the payment is authorized.

The Payment Authorization is finalized once the Klarna Network Session Token issued for the Payment Request is used to create a Payment Transaction. Until then, the Payment Request can be canceled, even if the Klarna Network Session Token has expired without being used.

The result depends on the Payment Request:

Payment Request	Result
`COMPLETED`, Payment Authorization not finalized	`200 OK`. The Payment Request moves to `CANCELED` with `state_reason` `PARTNER_CANCELED`. Klarna sends a `payment.request.state-change.canceled` webhook with `previous_state` `COMPLETED`.
`COMPLETED`, Payment Authorization finalized (a Payment Transaction was created)	`409 Conflict` with `error_code` `RESOURCE_CONFLICT` and the message `The payment authorization has been finalized and the payment request can no longer be canceled`. To reverse the payment, call voidPaymentTransaction or refundPaymentTransaction on the Payment Transaction instead.
`COMPLETED` tokenization-only request (no `amount`; a Customer Token was created)	`409 Conflict` with the message `Tokenization-only payment requests can not be canceled after the customer token is created`. This applies only to Payment Requests without an `amount`. A `COMPLETED` Payment Request with a one-time charge and a Customer Token is handled like any other `COMPLETED` Payment Request: it can be canceled until its Payment Authorization is finalized.
Already `CANCELED`	`200 OK` with the canceled Payment Request. The call is idempotent, and Klarna doesn't send a second webhook.
`DECLINED`	`409 Conflict` with `error_code` `RESOURCE_CONFLICT` and the message `Operation is not valid for the state: DECLINED`.
Past `expires_at`, including `EXPIRED`	`404 Not Found`.

After the cancellation

Klarna cancels the Klarna Network Session Token issued for the Payment Request:

If the Partner calls authorizePayment with this Klarna Network Session Token and includes step_up_config, Klarna returns STEP_UP_REQUIRED with result_reason KLARNA_NETWORK_SESSION_TOKEN_NOT_FOUND. Without step_up_config, Klarna returns DECLINED.
Calling readPaymentRequest for the canceled Payment Request returns 404 Not Found.

Customer Token not affected

Canceling a Payment Request doesn't revoke a Customer Token. The Customer Token stays valid.

Use cases

Cancel Payment Requests to keep the Klarna Payment Request lifetime aligned with the Partner's checkout. Common scenarios include checkout timeouts and error recovery.

Checkout timeout

The Payment Request lifetime must match the lifetime of the Partner's checkout. When the Partner's checkout closes or times out, call cancelPaymentRequest API

to close the Payment Request. Aligning the two keeps them in step and avoids handover issues with the Partner's own timeout logic.

Custom expiry alternative

Consider using the custom Payment Request expiry feature on createPaymentRequest API

(customer_interaction_config.interaction_expiry) to align Payment Request expiration times with the Partner's checkout timeout. This reduces the need for manual cancellation when the Partner's checkout times out.

Error recovery

When the Partner detects a non-recoverable error in the checkout flow before the customer enters the Klarna Purchase Journey (for example, an internal validation failure or a duplicate Payment Request), call cancelPaymentRequest API

to release the Payment Request and start a new one. This keeps the Klarna state aligned with the Partner's checkout state and prevents stale Payment Requests from blocking subsequent attempts.

Best practices

Proactive cancellation

Implement automatic cancellation for Payment Requests that have not completed within the expected timeframe. This helps:

Reduce unnecessary open Payment Requests
Improve Payment Request tracking and reporting
Free up system resources
Maintain clean Payment Request state

Webhook integration

Subscribe to the payment.request.state-change.canceled webhook to be notified when Payment Requests are canceled, whether by the Partner's system or by Klarna (due to expiration or other reasons).

Error handling

Implement proper error handling for cancellation failures:

Handle 409 Conflict errors for Payment Requests that can't be canceled: DECLINED Payment Requests, and COMPLETED Payment Requests whose Payment Authorization was finalized, or that were tokenization-only (no amount) and created a Customer Token.
Handle 404 Not Found errors for Payment Requests past expires_at, including EXPIRED ones.
Retry with exponential backoff for temporary failures
Log cancellation attempts for debugging and auditing

Set up your webhooks

Custom Payment Request expiry

Jump to section...