Custom Payment Request expiry

Customize how long a Payment Request stays valid using the interaction_expiry field. Configure expiration windows between 15 minutes and 48 hours using ISO 8601 durations or absolute timestamps.

Set a custom expiration window for a Payment Request

By default, a Payment Request expires 3 hours after creation. The interaction_expiry field overrides this default and aligns the Payment Request lifetime with the Partner's business requirements (a shorter window for flash sales or a longer one for complex purchases such as travel bookings).

Set interaction_expiry inside customer_interaction_config when calling createPaymentRequest API

. The resulting expiration is reflected in the expires_at field of the Payment Request response and remains in effect for the entire lifetime of the Payment Request, so it does not need to be repeated on subsequent calls. 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 does not match the 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 does not require clock synchronization between the Partner's 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).

SHELL

1 2 3 4 5 6 7 8 9 10

curl https://api-global.test.klarna.com/v2/payment/requests \
  -H 'Authorization: Basic <API key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "currency": "USD",
        "amount": 30000,
        "supplementary_purchase_data": {
          "purchase_reference": "order-7f3a9b2e",
          "line_items": [
            {

Response

The Payment Request's expires_at field reflects the custom expiry value provided.

Sample response

JSON

1 2 3 4 5 6 7 8 9 10

{
  "payment_request_id": "krn:payment:us1:request:552603c0-fe8b-4ab1-[...]",
  "payment_request_reference": "order-7f3a9b2e",
  "amount": 30000,
  "currency": "USD",
  "state": "SUBMITTED",
  "expires_at": "2025-01-01T12:30:00Z",
  "created_at": "2025-01-01T12:00:00Z",
  "updated_at": "2025-01-01T12:00:00Z",
  "state_context": {

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.
When 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 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

When the Payment Request expires before the customer completes the Klarna Purchase Journey, restart the flow with a new call to createPaymentRequest API

. Include the same payment context (amount, currency, supplementary_purchase_data) as the original request.

Best practices

Align expiry with the checkout session timeout: when the 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 such as PT30M do not require clock synchronization between the Partner's 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 prompting the customer to restart the checkout.
Keep session lifetimes aligned: 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.

Payment Request