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.
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.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_idof an existing Payment Request inSUBMITTEDorIN_PROGRESSstate
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
with the
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 to close the Payment Request. Aligning the two preserves session continuity and avoids handover issues with the Partner's own session-management logic.
to close the Payment Request. Aligning the two preserves session continuity and avoids handover issues with the Partner's own session-management logic.Consider using the custom Payment Request expiry feature on createPaymentRequest (
(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 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.
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, orDECLINED); the cancel operation is rejected. - Retry with exponential backoff for temporary failures
- Log cancellation attempts for debugging and auditing
Related articles