Reclaiming Unconverted Crypto

When a payment cannot be fully converted—because it was underpaid, overpaid, expired, invalid, or cancelled—Bead stores the residual crypto and prompts the customer to reclaim it. This page explains how that process works and what you, as an integrator, must do.

---

How Reclaim Flow Starts

Trigger statusCode	Typical Cause	Email Sent? *
underpaid	Customer sent less than requested	✔︎ if email captured
overpaid	Customer sent excess funds	✔︎ if email captured
expired	No funds before payment window closed	✔︎ if transaction detected after expired and email captured
invalid	Asset mismatch, multiple tx, compliance block	✔︎ if funds not from sanctioned wallet and email captured
cancelled	Customer or merchant cancelled after send	✔︎ if transaction detected and email captured

* Bead sends reclaim instructions to refundEmail (if supplied in the original payment request or collected on the hosted page).

A customer email is required to initiate the reclaim process. If no customer email was provided, re-present the hosted payment page to the customer to prompt them to provide their email. Alternatively, collect the customer email by other means and update it within the Bead payment via API.

---

Customer Reclaim Steps

1. Open the Reclaim page from the email link.

2. Specify a destination address based on the original asset.

3. Confirm network (including mainnet/testnet) and any applicable miner fee.

4. Submit request – Bead queues the refund on-chain.

5. Receive confirmation email once the transaction is broadcast.

Allow up to 24 hours for Reclaim transactions to complete.

After 30 days, unclaimed funds move to Bead’s treasury and require a support ticket for manual recovery. Bead reserves the right to convert unclaimed crypto for compliance purposes per our Terms.

Customers must specify a destination address as the original payment address may have been temporary or out of the customer's control.

---

Best Practices Checklist

✔︎ Best Practice	Why
Always supply refundEmail in the payment request or let the hosted page collect it	Ensures the customer receives reclaim instructions automatically
Listen for paymentNotifications in webhooks – type firstBlockReached, refundProcessed	Lets you update order status without polling
Surface a “Funds available to reclaim” banner in your UI when a webhook shows statusCode = underpaid, overpaid, expired, invalid, or cancelled	Provides guidance to customer; reduces support tickets
Treat the reclaim as customer-driven – do not attempt to refund on your own by sending crypto out manually	Prevents network, address, or fee errors; reduces liability; simplifies reconciliation
Store the final reclaim TXID (available in a follow-up webhook) for audit purposes	Completes the payment lifecycle record

---

Timing Windows

Parameter	Source	Default
paymentWindowInSeconds	/currencies endpoint	120 s
confirmationWindowInSeconds	/currencies	300 – 3600 s
Reclaim availability	Hard-coded	7 days from payment created