Timeouts

Payment requests have a limited time window during which users can complete their payments. Understanding these timeout settings is essential for proper error handling and user experience.

Default timeout

By default, a user has a total of 10 minutes to accept a payment. This breaks down as follows:

• 5 minutes to open the payment request in the app
• 5 minutes to approve it after opening

If the user doesn't complete the payment within this time window, the payment request will expire.

Important: Wait for the full timeout period

When implementing timeout handling, it's critical that your system waits for at least the full 10-minute timeout period before canceling an order or showing an error to the user.

If you cancel too early, you risk a poor user experience: The user may successfully confirm the payment in the app, only to immediately see an error message from your system saying the order has been canceled.

Best practice: Always wait for the full timeout period or use webhooks to receive real-time status updates before taking action on potentially expired payments.

What happens when a payment expires

When a payment request times out:

1. The payment status changes to EXPIRED
2. The user can no longer complete the payment
3. You will receive a webhook notification (if webhooks are configured) indicating the payment has expired
4. For PSP API implementations, a POST request is made to the makePaymentUrl with a status of timeout

The EXPIRED state is a final state - the payment cannot be recovered or modified after expiration.

Handling expired payments

When a payment expires, you should:

1. Monitor payment status: Use webhooks or poll the payment status to detect expired payments
2. Notify the user: Inform the customer that their payment request has expired
3. Create a new payment: If the customer still wants to complete the transaction, create a new payment request
4. Clean up: Update your internal systems to reflect the expired payment status

info

Implement webhooks to receive real-time notifications about payment status changes, including expirations.