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.

74 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 or IN_PROGRESS state

Cancelable states only

Payment Requests can only be canceled while in SUBMITTED or IN_PROGRESS states. Once a Payment Request reaches a final state (COMPLETED, EXPIRED, CANCELED, or DECLINED), it cannot 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-[...]",

Use cases

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

Session expiration

The Payment Request lifetime must match the Partner's checkout session. When the Partner's session terminates or expires, call cancelPaymentRequest API

to close the Payment Request. Aligning the two preserves session continuity and avoids handover issues with the Partner's own session-management 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 checkout session timeout. This reduces the need for manual cancellation when the Partner's session expires.

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 attempts to cancel Payment Requests already in a final state (COMPLETED, EXPIRED, CANCELED, or DECLINED); the cancel operation is rejected.
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...