Reclaiming Unconverted Crypto

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, should do.

How the reclaim flow starts

A reclaim flow is triggered when a payment ends in one of these statuses:

statusCode	Typical cause	Email sent*
underpaid	Customer sent less than requested	Yes if email captured
overpaid	Customer sent excess funds	Yes if email captured
expired	No funds before the payment window closed	Yes if funds arrive after expiry and email captured
invalid	Asset mismatch, multiple transactions, compliance block	Yes if funds are eligible and email captured
cancelled	Customer or merchant cancelled after sending funds	Yes if transaction detected and email captured

The reclaim email is sent to refundEmail when available. refundEmail can be:

• Supplied in the original payment request

• Collected on the hosted payment page

Customer email requirement

A customer email is required to initiate the reclaim process. If no email was captured:

• Re present the hosted payment page so the customer can enter their email, or

• Collect the customer email by another secure method and have it added to the Bead payment via API or support

Once an email is associated with the payment, Bead can send the reclaim link.

Customer reclaim steps

From the customer’s perspective, reclaiming funds works as follows:

1. Open the reclaim email The customer receives an email with a secure reclaim link when a qualifying status is reached and an email is on file.

2. Open the reclaim page The link opens a Bead hosted reclaim page for that payment.

3. Provide a destination address The customer enters a destination address for the original asset and network.

   • This address is under the customer’s control

   • The original payment address may have been temporary or managed by Bead or a provider

4. Confirm asset, network, and fees The page shows the asset to be returned, the network, and any applicable network fee.

5. Submit reclaim request Bead queues the refund on-chain and broadcasts the transaction.

6. Receive confirmation The customer receives a confirmation email after the reclaim transaction is broadcast.

Timing

• Allow up to 24 hours for reclaim transactions to complete

• After 30 days, unclaimed funds may move to Bead’s treasury and require a support ticket for manual recovery

• Bead may convert unclaimed crypto for compliance reasons as described in the Terms

Best practices for integrators

Always provide a refund email

• Include refundEmail in the payment request where possible, or allow the hosted page to collect it

• This ensures customers automatically receive reclaim instructions if a reclaimable status occurs

Listen to payment notifications

• Use webhooks rather than polling to detect reclaim related events

• Pay attention to paymentNotifications entries such as firstBlockReached and refundProcessed so you can update your internal order or ledger records

Clearly message reclaim in your UI

When a webhook shows statusCode of underpaid, overpaid, expired, invalid, or cancelled:

• Show a message such as “Funds available to reclaim”

• Let the customer know that instructions have been emailed to them

• Avoid implying that you will manually refund from your own wallet

Treat reclaim as a customer driven process

• Do not attempt to “help” by sending crypto out manually from your own wallets

• Redirect customers to the Bead reclaim email and page

• This reduces address mistakes, network mismatches, and fee surprises, and keeps liability and reconciliation simpler

Log reclaim activity

For each reclaim eligible payment, store:

• trackingId

• Requested amount and asset

• Amount eligible for reclaim

• Final reclaim transaction id (TXID), once available from follow up webhooks

• Reclaim completion date when the refund is processed

This gives you a complete lifecycle record for audits and customer support.

Timing windows and configuration

Several timing related values influence when a payment becomes reclaimable and how long reclaim is available.

Payment window

• paymentWindowInSeconds

  • Source: /currencies endpoint

  • Typical default: 120 seconds

  • How long the customer has to start and complete a payment before it is considered expired

Confirmation window

• confirmationWindowInSeconds

  • Source: /currencies endpoint

  • Typical defaults: 300 to 3600 seconds

  • How long Bead waits for network confirmations after funds are detected

Reclaim availability

• Reclaim window

  • Default: 7 days from the payment created timestamp

• After this period, reclaim requires manual intervention through Bead support and may be subject to additional compliance steps

Use the /currencies endpoint and the Settlement Currencies page in the Reference Guide to understand timing and configuration per asset and network, then design your customer messaging and internal processes to match those windows.