> 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/under-and-over-payment-handling.md).

# Under and Over Payment Handling

In crypto wallet payment flows, the customer types the amount they send, so the amount received can differ from the amount requested. This page explains how to handle payments that end as `overpaid` or `underpaid`.

{% hint style="warning" %}
**These two outcomes are handled differently.** `overpaid` is complete and paid: fulfill the order. `underpaid` is a declined payment: do not fulfill, and offer the customer a new payment. Both are final statuses.
{% endhint %}

### When this page applies

Use this page when the payment outcome is `overpaid` or `underpaid`.

If the payment ends as `expired`, `invalid`, or `cancelled`, use the [reclaim guidance](https://developers.bead.xyz/reference-guide/payment-scenarios/reclaiming-unconverted-crypto.md) instead.

If the payment was paid and the customer later wants money back, use the [refund and return guidance](https://developers.bead.xyz/reference-guide/payment-scenarios/refunds-for-crypto-and-wallet-payments.md) instead.

### What these outcomes mean

| Outcome     | What happened                                     | Paid? | What settles to the merchant | What goes back to the payer           |
| ----------- | ------------------------------------------------- | ----- | ---------------------------- | ------------------------------------- |
| `overpaid`  | The customer sent more than the requested amount. | Yes   | The requested amount         | The excess, through reclaim           |
| `underpaid` | The customer sent less than the requested amount. | No    | Nothing                      | The full amount sent, through reclaim |

A very small overpayment, within a per tender tolerance set by Bead, is classified as `completed` instead of `overpaid`. The payment settles normally and no reclaim is offered for the excess.

`overpaid` and `underpaid` are final statuses. `statusCode` does not change when the payer reclaims their funds. Reclaim progress is reported in `refundLifecycleStatus`, which reaches `completed` when the return is done. If the payer never reclaims, or the amount is below the minimum that can be returned, `refundLifecycleStatus` does not reach `completed`.

{% hint style="info" %}
**Note for testing:** After a reclaim completes, some paths can still return `partiallyRefunded` or `fullyRefunded` in `statusCode`. This is being removed in an upcoming update. Do not build logic around these values. Treat the payment as final, and keep your fulfillment decision from the first outcome. `statusCode` will stay `overpaid` or `underpaid`, and reclaim progress is reported in `refundLifecycleStatus`.
{% endhint %}

### How to handle an overpaid payment

An `overpaid` payment is complete and paid. When a payment ends as `overpaid`:

* Treat the payment as complete and paid
* Fulfill the order, the same as for `completed`
* Mark the order or invoice as paid
* Do not ask the customer to pay again
* Tell the customer they sent more than requested and that the excess will be returned through Bead's reclaim process
* Expect later webhooks as the return of the excess progresses, with `statusCode` still `overpaid`. Keep the order fulfilled

The requested amount is batched and settled to the merchant like a `completed` payment. The excess is held separately and returned to the payer. It is not part of the merchant's settlement.

### How to handle an underpaid payment

When a payment ends as `underpaid`:

* Do not fulfill the order
* Treat it like a declined payment. Nothing was processed for the order
* Do not ask the customer to send the difference to the same payment session. The session cannot be topped up
* Offer the customer a new payment, with the same tender or a different one
* Tell the customer the amount they sent will be returned through Bead's reclaim process
* Expect later webhooks as the return progresses, with `statusCode` still `underpaid`

### Reclaim versus refund

Keep these flows separate.

**Reclaim** is how Bead returns crypto to the payer that was not part of a paid amount. It applies to the excess on `overpaid`, and to the full amount received on `underpaid`, `expired`, `invalid`, and `cancelled`. Bead runs the reclaim flow. Your integration does not.

**Refund or return** guidance applies when the merchant later decides to return value to the customer for a paid order, under its normal return policy. Bead has no refund endpoint.

A completed reclaim is not a merchant initiated refund. When the excess on an `overpaid` payment is returned, the order has not been returned.

### Webhooks and status handling

Your integration should:

* Listen for payment status changes through webhooks
* Act on the first outcome for the payment: fulfill on `overpaid`, decline on `underpaid`
* Expect further webhooks as the reclaim progresses. Bead sends a payment webhook each time `refundLifecycleStatus` changes, with the payment's final `statusCode` unchanged
* Treat those later webhooks as record updates, not as a new fulfillment decision
* Avoid building merchant logic that assumes every customer will send the exact requested amount

See [Tracking Reclaim Status](https://developers.bead.xyz/reference-guide/payment-scenarios/tracking-reclaim-status.md) for the reclaim fields and lifecycle values.

### Customer messaging guidance

Clear customer messaging reduces support friction.

**Suggested guidance for overpaid payments**

> Your payment was received and your order is confirmed. You sent more than the amount due, and the extra amount will be returned to you. Check your email for instructions to claim it.

**Suggested guidance for underpaid payments**

> Your payment did not go through because the amount received was lower than the amount due. The amount you sent will be returned to you. Check your email for instructions to claim it. To complete your purchase, please start a new payment.

### Fulfillment guidance

| Payment outcome                   | Fulfillment behavior                                                     |
| --------------------------------- | ------------------------------------------------------------------------ |
| `completed`                       | Fulfill normally                                                         |
| `overpaid`                        | Complete and paid. Fulfill normally. The excess is returned to the payer |
| `underpaid`                       | Do not fulfill. Offer a new payment                                      |
| `expired`, `invalid`, `cancelled` | Do not fulfill. Follow the applicable reclaim or exception flow          |

### Best practices

* Fulfill on `overpaid` exactly as you do on `completed`
* Treat `underpaid` as a decline and create a new payment for any retry
* Keep reclaim handling separate from merchant refund handling
* Make your webhook processing idempotent, and expect reclaim progress events after the outcome
* Store the requested amount, the amount received, the outcome, and the order decision for support and reconciliation

### Related pages

* [Reclaiming Unconverted Crypto](https://developers.bead.xyz/reference-guide/payment-scenarios/reclaiming-unconverted-crypto.md)
* [Tracking Reclaim Status](https://developers.bead.xyz/reference-guide/payment-scenarios/tracking-reclaim-status.md)
* [Payment Statuses](https://developers.bead.xyz/payments/payment-statuses.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/under-and-over-payment-handling.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.
