> 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 leave crypto with Bead that is not part of a paid amount. In these cases, Bead returns that 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                                          |
| ----------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `overpaid`  | The payer sent more than the requested amount. The payment is paid and the requested amount settles to the merchant. | The excess only: the amount paid minus the amount requested. |
| `underpaid` | The payer sent less than the requested amount. The payment is not paid and nothing settles.                          | The full amount received.                                    |
| `expired`   | No valid payment was completed before the payment window expired.                                                    | Any funds received.                                          |
| `invalid`   | Irregular event such as multiple transactions, unsupported asset, compliance block, or extreme market movement.      | Any funds received.                                          |
| `cancelled` | The payment was cancelled before completion.                                                                         | Any funds received.                                          |

All of these are final statuses. A reclaim does not change `statusCode`. Its progress is reported in `refundLifecycleStatus`.

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

A very small overpayment, within a per tender tolerance set by Bead, is classified as `completed` instead of `overpaid`, and no reclaim is offered for it.

#### 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 leave funds with Bead that are not part of a paid amount.

Reclaim provides a consistent and compliant way to return that 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 `overpaid`, `underpaid`, `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 reclaimable crypto to the provided address
6. Bead updates the payment record, sends a payment webhook, and emails the payer a receipt for the return

For `overpaid`, the customer receives the excess they sent. For `underpaid`, the customer receives the full amount they sent. In both cases the network cost of the return transfer can reduce the amount that arrives. The receipt shows the claim amount, the claim cost, and the amount returned.

If the reclaimable amount is below the minimum that can be transferred on that network (for example, 1 USDC for USDC payments), the reclaim page shows the reclaim as unavailable and no return is sent. `refundLifecycleStatus` does not reach `completed`.

#### Tracking reclaim status

Reclaim progress is visible on the payment record. `refundLifecycleStatus` moves through `emailSent`, `customerClaimed`, and `processing` to `completed`, with `failed` and `rejected` for returns that could not be completed. `refundInitiatedAt` is set when the payer is first emailed reclaim instructions or starts a claim, and `refundCompletedAt` is set when Bead confirms the return. `statusCode` does not change.

Bead sends a payment webhook each time `refundLifecycleStatus` changes. You can also read the reclaim fields from `GET /Payments/{paymentId}/tracking`, `GET /Payments/{paymentId}`, or merchant and partner payment history. See [Tracking Reclaim Status](https://developers.bead.xyz/reference-guide/payment-scenarios/tracking-reclaim-status.md) for the fields, lifecycle values, webhook handling, and example responses.

#### 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                                                          |
| --------------------------------- | ----------------------------------------------------------------------------- |
| `overpaid`                        | Paid. Fulfill the order. The excess is returned to the payer through reclaim. |
| `underpaid`                       | Not paid. Do not fulfill. Offer the customer a new payment.                   |
| `expired`, `invalid`, `cancelled` | Not paid. Do not fulfill.                                                     |

#### Suggested UI messaging

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

**Overpaid**

> Payment received and your order is confirmed. You sent more than the amount due. The extra amount will be returned to you through the reclaim process. Check your email for instructions.

**Underpaid**

> Payment not completed. The amount sent was less than the amount due. The crypto that was sent will be returned to you through the reclaim process. Please start a new payment to complete your purchase.

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

After the 30-day window, the reclaim link no longer works. 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**

The network cost of the return transfer can reduce the amount the payer receives, depending on the asset and network. The payer's receipt shows the claim amount, the claim cost, and the amount returned.

**Minimum amount**

A reclaim below the minimum transfer amount for the network cannot be sent. For USDC, the minimum is 1 USDC.

**Customer support visibility**

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

* `paymentId`
* `statusCode`
* `refundLifecycleStatus` and `refundCompletedAt`
* 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. An underpaid payment cannot be topped up. If the payer still wants to pay, create a new payment and direct the payer to the new hosted payment page.

**Should the merchant refund the excess on an overpaid payment?**

No. Bead returns the excess to the payer through reclaim. The merchant is settled the requested amount only.

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

**How do I know when the return is complete?**

Listen for the payment webhook where `refundLifecycleStatus` is `completed`, or read the payment record. At that point `refundCompletedAt` is set. `statusCode` keeps its final value. See [Tracking Reclaim Status](https://developers.bead.xyz/reference-guide/payment-scenarios/tracking-reclaim-status.md).

**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](https://developers.bead.xyz/payments/payment-statuses.md)
* [Under and Over Payment Handling](https://developers.bead.xyz/reference-guide/payment-scenarios/under-and-over-payment-handling.md)
* [Tracking Reclaim Status](https://developers.bead.xyz/reference-guide/payment-scenarios/tracking-reclaim-status.md)
* [Payment Webhooks](https://developers.bead.xyz/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
