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 for full details on reclaim timing, windows, and the customer experience.
Integrator handling
Order and fulfillment
Treat
expiredas 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":
Verify the webhook signature.
Persist the event.
Update your internal order or invoice to a non-success state.
Surface appropriate messaging to the customer.
Return
2xxpromptly.
Use trackingId + statusCode as your idempotency key. See Payment Webhooks 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:
When the customer may have sent funds after expiry:
Scenario routing
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
Last updated