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 if the Partner's checkout timeout is shorter than the Payment Request lifetime. By default, a Payment Request remains open for 3 hours and will automatically expire if not completed or explicitly canceled. You can override this default with the custom Payment Request expiry feature.

Prerequisites

Before canceling a Payment Request, ensure the following:

A valid Partner Account with API credentials
Backend capability to receive and process Klarna webhooks
An existing Payment Request that can be canceled
The payment_request_id of the Payment Request to cancel

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/accounts/{partner_account_id}/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": "acquiring-partner-request-reference-1234",
  "amount": 11836,
  "currency": "EUR",

Webhook

Subscribe to the payment.request.state-change.canceled webhook event using the guidelines provided here. 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 Acquiring Partner stop a purchase after the customer completes the Klarna Purchase Journey, for example when the Acquiring 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 Acquiring 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 in various scenarios to maintain accurate payment tracking and free up resources. Common scenarios include abandoned checkouts, checkout timeouts, and error recovery.

Abandoned checkout

Cancel the Payment Request when the customer abandons the checkout flow.

SHELL

1 2 3

curl -X DELETE https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/payment/requests/krn:payment:eu1:request:abc123 \
  -H 'Authorization: Basic <API key>'

Checkout timeout

Proactively cancel Payment Requests when the Partner's checkout times out to avoid unnecessary open requests.

Align expiry with session timeout

Consider using the custom Payment Request expiry feature in authorizePayment API

(step_up_config.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.

SHELL

1 2 3 4

# Cancel payment request after 30-minute session timeout
curl -X DELETE https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/payment/requests/{payment_request_id} \
  -H 'Authorization: Basic <API key>'

Best practices

Proactive cancellation

Implement automatic cancellation for Payment Requests that haven't completed within your 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 your 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

Custom Payment Request expiry

Setup your webhooks

Jump to section...