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.

6 min read

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 interaction_expiry inside step_up_config.customer_interaction_config when calling authorizePayment API

. 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

Recommended for integration

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`

Expiry range limits

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",

Custom expiry example

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 EXPIRED state.
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 API

. 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_expiry to PT30M. This prevents orphaned Payment Requests that stay open after the session ends.
Use duration for relative timeouts. Duration values like PT30M don'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 timestamp format.
Subscribe to expiry Klarna webhooks. Handle the payment.request.state-change.expired event 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.

Payment Request

Cancel a Payment Request

Jump to section...