> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/reference-guide/payment-scenarios/expired-payment-handling.md).

# Expired Payment Handling

#### Purpose

This page explains what happens when a payment reaches the `expired` status, how to handle it in your integration, and what the customer experiences.

Use this page when a payment status check or webhook returns `expired` and you need to know what to do next.

#### What causes an expired payment?

Each Bead payment is backed by a crypto quote — a fixed conversion rate valid for a limited window. If the customer does not complete the wallet transfer before the quote window closes, the payment moves to `expired`.

The hosted payment page gives the customer a short window to request a new quote before the session ends. If the customer does not act within that window, the payment is automatically marked `expired`.

Expiry is not caused by merchant or integrator action. It is driven entirely by the quote window timing out.

#### What happens to funds sent after expiry?

If a customer sends funds after the payment has expired:

* the funds are not converted
* they remain unconverted and are returned to the payer through Bead's reclaim process
* Bead emails reclaim instructions to the payer if an email address is available

The integrator does not need to implement the crypto return flow. See [Reclaiming Unconverted Crypto](/reference-guide/payment-scenarios/reclaiming-unconverted-crypto.md) for full details on reclaim timing, windows, and the customer experience.

#### Integrator handling

**Order and fulfillment**

* Treat `expired` as a terminal non-success state.
* Do not fulfill the order.
* Do not reuse the expired payment URL — it cannot be resumed or extended.
* If the customer still wants to pay, create a new payment and direct them to the new hosted payment URL.

**Internal state mapping**

Map `expired` to a non-success internal state such as:

* Payment expired
* Session timed out
* Awaiting new payment

Do not map `expired` to paid, approved, or any fulfillable state.

**Webhook handling**

When your webhook consumer receives a payload with `statusCode: "expired"`:

1. Verify the webhook signature.
2. Persist the event.
3. Update your internal order or invoice to a non-success state.
4. Surface appropriate messaging to the customer.
5. Return `2xx` promptly.

Use `trackingId` + `statusCode` as your idempotency key. See [Payment Webhooks](/payments/payment-webhooks.md) for signature verification and processing guidance.

#### Customer experience

**In the hosted UI**

When the quote is about to expire, the hosted payment page gives the customer a short window to request a new quote. If no action is taken, the session ends and the payment moves to `expired`.

The customer cannot resume the expired session. They must start a new payment.

**If funds were sent after expiry**

Bead initiates reclaim after the payment expires if funds are received. If a `refundEmail` was included in the original payment request, Bead emails the customer reclaim instructions automatically. If no email was provided, the hosted page prompts the customer for an email when reclaim is required.

The self-serve reclaim window is 7 days from the payment created timestamp. Customers who miss that window should contact support.

#### Suggested UI messaging

Use clear, direct messaging so the customer knows what happened and what to do next.

**When the payment expires before the customer pays:**

```
Your payment session expired before a payment was detected. To complete your
purchase, please start a new payment.
```

**When the customer may have sent funds after expiry:**

```
Your payment session expired before a payment was detected. If you sent funds
after the session ended, they will be returned to you through the reclaim
process. To try again, please start a new payment.
```

#### Scenario routing

| Situation                                                                | What to do                                                                                   |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| Payment reached `expired`, no funds sent                                 | Create a new payment if the customer wants to try again                                      |
| Payment reached `expired`, customer may have sent funds late             | Direct customer to check for a reclaim email; create a new payment if they want to try again |
| Customer sent funds just before expiry but payment still shows `expired` | Funds are handled through reclaim; create a new payment for the purchase                     |
| Customer wants to resume the expired session                             | Not possible — create a new payment                                                          |

#### Related pages

* [Payment Statuses](/payments/payment-statuses.md)
* [Reclaiming Unconverted Crypto](/reference-guide/payment-scenarios/reclaiming-unconverted-crypto.md)
* [Under- and Over-Payment Handling](/reference-guide/payment-scenarios/under-and-over-payment-handling.md)
* [Payment Webhooks](/payments/payment-webhooks.md)
* [Why Did My Payment Expire, and What Happens Next?](/faqs-and-troubleshooting/payments-faqs/why-did-my-payment-expire-and-what-happens-next.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.bead.xyz/reference-guide/payment-scenarios/expired-payment-handling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.