Custom Payment Request expiry
Customize how long a Payment Request stays valid using the interaction_expiry field in the Payment Authorize API. Configure expiration windows between 15 minutes and 48 hours using ISO 8601 durations or absolute timestamps.
Set a custom expiration window for Payment Requests created during the step-up authorization flow
By default, a Payment Request created during a step-up flow expires 3 hours after creation. Use the
interaction_expiry field to override this default and align the Payment Request lifetime with your Partner's business requirements — whether that means a shorter window for flash sales or a longer one for complex purchases like travel bookings.Set 
. The resulting expiration is reflected in the
interaction_expiry inside step_up_config.customer_interaction_config when calling authorizePayment. The resulting expiration is reflected in the expires_at field of the Payment Request response. After expires_at, the Payment Request is expired and deleted, and no further actions can be taken on it.When to use
Use
interaction_expiry when the default 3-hour window doesn't match your Partner's business requirements.| Scenario | Suggested format | Example value | Why |
|---|---|---|---|
| Airline and travel bookings | Duration | "duration": "PT15M" | Flight fares change frequently — a short window ensures the quoted price is still valid when the customer completes payment |
| Flash sales, limited-time offers | Duration | "duration": "PT15M" | Short window prevents customers from holding expired deals |
| In-store kiosk or point-of-sale | Duration | "duration": "PT30M" | Matches typical kiosk session timeout |
| Standard online checkout | Duration | "duration": "PT1H" | Gives customers time without keeping Payment Requests open too long |
| Complex purchases (insurance, custom orders) | Duration | "duration": "PT24H" | Allows time for multi-step decisions |
| Hard deadline (event tickets, auction closing) | Timestamp | "timestamp": "2025-06-15T18:30:00Z" | Payment Request expires at the exact moment the offer ends |
Duration is recommended for most use cases. It doesn't require clock synchronization between your server and Klarna, making it simpler and less error-prone.
Expiry formats
The
interaction_expiry field accepts one of two formats. Provide exactly one — either duration or timestamp.| Format | Field | Type | Constraints | Examples |
|---|---|---|---|---|
| Duration | duration | string — ISO 8601 duration | 2–25 characters. Must resolve to between 15 minutes and 48 hours from creation. | PT15M (15 min), PT1H (1 hour), PT2H30M (2.5 hours), P1D (1 day), PT48H (48 hours) |
| Timestamp | timestamp | string — ISO 8601 date-time with timezone | Must be between 15 minutes and 48 hours from the time of Payment Request creation. | 2025-06-15T18:30:00Z, 2025-12-31T23:59:59Z |
The expiry value must resolve to between 15 minutes and 48 hours from the time of Payment Request creation. Values outside this range return a
400 Bad Request error.Request
The field applies to all customer interaction methods (
HANDOVER, QR_CODE, HEADLESS).SHELL
1
2
3
4
5
6
7
8
9
10
curl https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/payment/authorize \
-H 'Authorization: Basic <API key>' \
-H 'Content-Type: application/json' \
-H 'Klarna-Network-Session-Token: krn:network:us1:test:session-token:eyJhbGciOiJIU[...]' \
-d '{
"currency": "USD",
"supplementary_purchase_data": {
"purchase_reference": "order-7f3a9b2e",
"line_items": [
{Response
When the authorization returns
STEP_UP_REQUIRED, the Payment Request's expires_at field reflects the custom expiry value you provided.Sample response
JSON
1
2
3
4
5
6
7
8
9
10
{
"payment_transaction_response": {
"result": "STEP_UP_REQUIRED"
},
"payment_request": {
"payment_request_id": "krn:payment:us1:request:552603c0-fe8b-4ab1-[...]",
"payment_request_reference": "acquiring-partner-request-ref-1234",
"amount": 30000,
"currency": "USD",
"state": "SUBMITTED",In this example, the Payment Request was created at
12:00:00Z with a duration of PT30M, so expires_at is 12:30:00Z — 30 minutes after creation instead of the default 3 hours.What happens after expiry
After the
expires_at timestamp passes:- 1.The Payment Request transitions to the
EXPIREDstate. - 2.Klarna deletes the Payment Request, and no further actions can be taken on it.
- 3.If the customer attempts to complete the Klarna Purchase Journey after expiry, it fails.
Webhook event
Subscribe to the
payment.request.state-change.expired Klarna webhook to detect when a Payment Request expires. Use this event to notify the Partner or prompt the customer to restart the checkout.Sample webhook payload
JSON
1
2
3
4
5
6
7
8
9
10
{
"metadata": {
"event_type": "payment.request.state-change.expired",
"event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"event_version": "v2",
"occurred_at": "2025-01-01T12:30: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-[...]",Restarting after expiry
If the Payment Request expires before the customer completes the step-up, restart the authorization flow with a new call to authorizePayment. Include the same payment context (
. Include the same payment context (amount, currency, supplementary_purchase_data) as the original request.Best practices
- Align expiry with the Partner's checkout session timeout. If the Partner's checkout session expires in 30 minutes, set
interaction_expirytoPT30M. This prevents orphaned Payment Requests that stay open after the session ends. - Use duration for relative timeouts. Duration values like
PT30Mdon't require clock synchronization between your server and Klarna, making them simpler and less error-prone. - Use timestamps for hard deadlines. When the Payment Request must expire at a specific point in time — for example, when a fare lock or auction closes — use the
timestampformat. - Subscribe to expiry Klarna webhooks. Handle the
payment.request.state-change.expiredevent to detect expirations and take appropriate action, such as notifying the Partner or prompting the customer to restart the checkout. - Cancel proactively when the customer abandons checkout. Don't wait for expiry if the customer leaves the checkout flow. Use cancelPaymentRequest to close the Payment Request immediately. See Cancel a Payment Request for details.
Related articles
API & SDK references