> 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/reclaiming-unconverted-crypto.md).

# Reclaiming Unconverted Crypto

## 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 transaction is not completed.                                | The full amount received is reclaimable because nothing is converted or 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:

* A payment ends in a reclaimable status
* 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. If email is not yet available at that point, the hosted payment page collects it directly — see below.

#### 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.

Behavior differs by terminal type.

**Virtual terminals**

`refundEmail` is required on virtual terminal payment requests. This applies regardless of whether a `customer` object is also included, and a `customer.email` value does not substitute for it. A virtual terminal request that omits `refundEmail` returns `400 Bad Request`, even if a complete `customer` object with `email` is present.

**Physical terminals**

`refundEmail` is optional. If it is omitted but the request includes a `customer` object with `email`, Bead uses `customer.email` as the reclaim email automatically. If neither `refundEmail` nor `customer.email` is available, the hosted payment page prompts the payer to enter an email at the point reclaim is needed.

| Terminal type | `refundEmail` omitted, no `customer.email`                        | `refundEmail` omitted, `customer.email` present                        | `refundEmail` supplied                     |
| ------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------ |
| Virtual       | `400 Bad Request` — `refundEmail` is required                     | `400 Bad Request` — `refundEmail` is required regardless of `customer` | Reclaim instructions emailed automatically |
| Physical      | Hosted page prompts the payer for an email when reclaim is needed | Reclaim instructions emailed to `customer.email` automatically         | Reclaim instructions emailed automatically |

Send `refundEmail` as `null` rather than omitting it if your integration always includes the key but sometimes has no value yet to send on a physical terminal request. Do not send `refundEmail` as an empty string on any terminal type — an empty string is not treated the same as an absent or `null` value and can prevent Bead from having an email on file for reclaim.

#### 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, or prompts the payer for one on the hosted page first if it is not
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 both `underpaid` and `overpaid`, the customer receives the full amount they sent, as the full amount remains unconverted and is eligible for reclaim.

#### Integrator responsibilities

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

| 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 not successful payment. Do not fulfill. Create a new payment if the customer wants to try again. |
| `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 not completed. The amount sent was more than requested. The full crypto amount you sent will be returned through the reclaim process. Please start a new payment to try again.

**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

On virtual terminals, `refundEmail` is required. Include it on every virtual terminal payment request, in addition to the required `customer` object.

On physical terminals, provide `refundEmail` up front if you can so the customer does not need to re-enter it later. If you omit it, a `customer.email` on the request is used automatically. If you send neither, the hosted payment page collects an email if reclaim is later needed.

If you send a `customer` object, ensure it is complete. Providing partial customer data may trigger required field validation.

#### Timing and reclaim windows

There is a single reclaim window: **30 days**, counted from the payment's last-updated timestamp, not its created timestamp. Any update to the payment record resets the 30-day clock from that point.

|                |                                                   |
| -------------- | ------------------------------------------------- |
| Reclaim window | 30 days from the payment's last-updated timestamp |

This is a single global setting, not a value that varies by merchant, partner, or terminal.

Nothing is automated at the end of the 30-day window. Unclaimed funds are not swept, forfeited, or moved into a separate Bead-controlled handling process — they remain with the merchant. If a payer has not completed reclaim within the window, they should contact support.

#### 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
* 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?**

On physical terminals, yes. If neither `refundEmail` nor `customer.email` was available on the original request, the hosted payment page prompts 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.

Virtual terminals require `refundEmail` on the original request, so this scenario does not apply there.

#### Related pages

* [Payment Statuses](/payments/payment-statuses.md)
* [Under and Over Payment Handling](/reference-guide/payment-scenarios/under-and-over-payment-handling.md)
* [Payment Webhooks](/payments/payment-webhooks.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, and the optional `goal` query parameter:

```
GET https://developers.bead.xyz/reference-guide/payment-scenarios/reclaiming-unconverted-crypto.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.