Reclaiming Unconverted Crypto

Reclaiming Unconverted Crypto

Some payment outcomes result in crypto being received by Bead but not converted. In these cases, Bead returns the unconverted crypto to the payer through the reclaim flow.

This page explains when reclaim happens, how email is captured, what the customer experiences, and how integrators should handle these scenarios.

When reclaim happens

Reclaim can be required when a payment ends in one of these statuses:

statusCode	What happens	What is reclaimable
underpaid	The payer sent less than the requested amount. The transaction is not completed.	The full amount received is reclaimable because nothing is converted or settled.
overpaid	The payer sent more than the requested amount. The requested amount is processed.	Only the overage is reclaimable. The requested amount is processed and settled.
expired	No valid payment was completed before the payment window expired.	Any funds received remain unconverted and are reclaimable.
invalid	Irregular event such as multiple transactions, unsupported asset, compliance block, or extreme market movement.	Any funds received remain unconverted and are reclaimable.
cancelled	The payment was cancelled before completion.	Any funds received remain unconverted and are reclaimable.

Reclaim returns crypto in the same asset and network that was received, subject to the constraints described below.

Why reclaim exists

In wallet based crypto payments, the payer often enters the crypto amount manually in their wallet app after scanning a QR code. Mistyped amounts and other non standard conditions can cause funds to be received but not eligible for conversion and settlement.

Reclaim provides a consistent and compliant way to return unconverted crypto to the payer without requiring the integrator to build a custom crypto return flow.

How the reclaim flow starts

Bead initiates reclaim after:

1. A payment ends in a reclaimable status

2. Bead has an email address for the payer

When email is available, Bead sends the payer an email that contains instructions and a reclaim link.

Email capture and the refundEmail field

Bead uses an email based reclaim flow.

If the integrator provides an email in the original payment request, Bead uses it to send reclaim instructions.

In the Payments API, the email field used for this purpose is named refundEmail. The field name stays the same, but in this context it means:

• where reclaim instructions are sent

• not a merchant initiated refund

Common patterns

Environment	Typical behavior
Digital or virtual checkout	The integrator usually provides customer email in the Create Payment request, so reclaim instructions can be sent automatically.
Physical or terminal based checkout	Customer email is often not provided. When an underpaid or overpaid outcome occurs, the hosted payment page prompts the payer to enter an email so reclaim can proceed.

What the customer experiences

The reclaim experience is driven by the email link and the hosted reclaim flow.

A typical customer journey looks like this:

1. Customer pays via wallet and the payment ends as underpaid, overpaid, expired, invalid, or cancelled

2. Bead emails reclaim instructions when an email address is available

3. Customer opens the reclaim link

4. Customer confirms a destination wallet address for the return

5. Bead returns the unconverted crypto to the provided address

For overpaid, the customer receives only the overage. For underpaid, the customer receives the full amount they sent.

Integrator responsibilities

Integrators do not implement the crypto return process directly, but you should handle the customer experience and internal state correctly.

Recommended integrator behavior

statusCode	Recommended behavior
underpaid	Treat as not successful payment. Do not fulfill. Create a new payment if the customer wants to try again.
overpaid	Treat as successful payment for the requested amount. Fulfill once confirmed. Do not attempt to return the overage yourself.
expired, invalid, cancelled	Treat as not successful payment. Do not fulfill.

Suggested UI messaging

You can adapt the wording below for your checkout UI or support flows.

Underpaid Payment not completed. The amount sent was less than requested. The crypto that was sent will be returned through the reclaim process. Please start a new payment to try again.

Overpaid Payment completed for the requested amount. An extra amount was received and will be returned through the reclaim process.

Expired, invalid, cancelled Payment not completed. If any crypto was sent, it will be returned through the reclaim process.

Providing the reclaim email in Create Payment

If you can, provide the reclaim email up front so the customer does not need to re enter it later.

Example snippet:

{
  "refundEmail": "[email protected]"
}

If you also send a customer object, ensure it is valid if present. Providing partial customer data may trigger required field validation.

Timing and reclaim windows

Reclaim timing is controlled by two concepts.

Self serve reclaim window

By default, the self serve reclaim link is valid for a limited window starting from the payment created timestamp.

Default window 7 days from the payment created timestamp

If the payer attempts reclaim after the self serve window expires, the reclaim link may no longer work and the payer must contact support.

Long stop handling

Unclaimed funds are not held indefinitely. After a longer holding period, unclaimed funds may be moved into Bead controlled handling, subject to policy, compliance requirements, and operational constraints.

Typical long stop period 30 days from the payment created timestamp

The 7 day window is the standard self serve experience. The 30 day period is a longer term handling boundary. If a payer misses the 7 day window, they should contact support as soon as possible and well before the long stop period.

Constraints and important notes

Asset and network

Reclaim returns crypto in the original asset and network that was received. The customer must provide a compatible destination address.

Fees and exact amounts

Network fees may apply to the return transaction. The returned amount may be reduced by applicable network fees, depending on the asset, network, and reclaim method.

Customer support visibility

For operational tracking, integrators should store and be ready to share:

• trackingId

• statusCode

• amount requested

• amount received

• for overpaid, the settleable portion and the overage

• customer email used for reclaim instructions, if provided

Frequently asked questions

Can the payer send additional funds to fix an underpayment?

No. Underpaid payments are treated as not completed. If the payer still wants to pay, the integrator should create a new payment and direct the payer to the new hosted payment page.

Do integrators need to implement the reclaim return transaction?

No. Bead handles the crypto return flow. Integrators should surface clear messaging and route support questions appropriately.

If the payer did not provide an email, can reclaim still happen?

Yes. In many physical flows, the hosted payment page will prompt the payer for an email when reclaim is required. Once collected, Bead sends the reclaim instructions.

If the payer closes the flow before providing an email, reclaim cannot start until an email address is captured.

Related pages

• Payment Statuses

• Under and Over Payment Handling

• Payments Webhooks

• Reporting and Settlement APIs