> 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.md).

# Payment Scenarios

## Payment Scenarios

### Purpose

Payment Scenarios explains how to handle outcomes other than a straightforward `completed` payment.

Use this section when a payment does not follow the standard completed flow, or when your business team needs guidance on what to do next after a real-world exception such as an overpayment, an underpayment, a reclaimable balance, or a return request.

This section is not the primary home for creating payments, checking basic payment status, or configuring payment webhooks.

* Go to [Payments](https://developers.bead.xyz/payments.md) for payment creation, payment statuses, wallet flows, payment webhooks, receipts, and test transactions.
* Go to [Operational Guides](https://developers.bead.xyz/reference-guide/operational-guides.md) for supplemental production guidance such as webhook hardening and wallet compatibility.
* Go to [Reporting](https://developers.bead.xyz/reporting.md) and [Settlement](https://developers.bead.xyz/settlement.md) when you need historical or financial records across many payments.

### What you’ll find here

| Page                                                                                                                                              | When to read it                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| [Under and Over Payment Handling](https://developers.bead.xyz/reference-guide/payment-scenarios/under-and-over-payment-handling.md)               | The customer sends more or less crypto than requested and the payment ends as `overpaid` or `underpaid`.                   |
| [Reclaiming Unconverted Crypto](https://developers.bead.xyz/reference-guide/payment-scenarios/reclaiming-unconverted-crypto.md)                   | A payment ends as `overpaid`, `underpaid`, `expired`, `invalid`, or `cancelled`, and crypto must be returned to the payer. |
| [Tracking Reclaim Status](https://developers.bead.xyz/reference-guide/payment-scenarios/tracking-reclaim-status.md)                               | You need to see where a reclaim stands and when the return to the payer has completed.                                     |
| [Refunds for Crypto and Wallet Payments](https://developers.bead.xyz/reference-guide/payment-scenarios/refunds-for-crypto-and-wallet-payments.md) | You need return-policy guidance for paid crypto or wallet payments and need to understand how refunds differ from reclaim. |

### How to use this section

1. Start with the payment outcome reported by your webhook or payment status response.
2. If the payment is `overpaid` or `underpaid`, open [Under and Over Payment Handling](https://developers.bead.xyz/reference-guide/payment-scenarios/under-and-over-payment-handling.md).
3. If crypto is being returned to the payer, open [Reclaiming Unconverted Crypto](https://developers.bead.xyz/reference-guide/payment-scenarios/reclaiming-unconverted-crypto.md).
4. To follow a reclaim through to completion, open [Tracking Reclaim Status](https://developers.bead.xyz/reference-guide/payment-scenarios/tracking-reclaim-status.md).
5. If the payment was paid and the business wants to return funds afterward, open [Refunds for Crypto and Wallet Payments](https://developers.bead.xyz/reference-guide/payment-scenarios/refunds-for-crypto-and-wallet-payments.md).
6. Apply the business handling in your UI, support workflow, and internal reconciliation process.

### Scenario routing guide

Every outcome below is a final status. A reclaim does not change it.

| Payment outcome                                                 | What it means for the business                                                                                                                                                         |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `completed`                                                     | Paid. Follow your normal fulfillment workflow.                                                                                                                                         |
| `overpaid`                                                      | Paid. Fulfill the order. The requested amount settles to the merchant and the excess is returned to the payer through reclaim.                                                         |
| `underpaid`                                                     | Not paid. Treat as declined and do not fulfill. Offer the customer a new payment. The amount sent is returned to the payer through reclaim.                                            |
| `expired`                                                       | Not paid. Do not fulfill. If funds later arrive, they are handled through reclaim.                                                                                                     |
| `invalid`                                                       | Not paid. Do not fulfill. Any eligible funds are handled through reclaim.                                                                                                              |
| `cancelled`                                                     | Not paid. Do not fulfill. Any remaining funds may be reclaimed.                                                                                                                        |
| Reclaim progress on any of the above                            | `statusCode` does not change. Follow `refundLifecycleStatus`. See [Tracking Reclaim Status](https://developers.bead.xyz/reference-guide/payment-scenarios/tracking-reclaim-status.md). |
| Customer wants money back after a paid crypto or wallet payment | Follow the refund or return guidance for paid orders, which is separate from reclaim.                                                                                                  |

### Related sections

| Section                                                                                 | Use it for                                                                                |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [Payments](https://developers.bead.xyz/payments.md)                                     | Core payment API flows, hosted checkout, payment statuses, receipts, and payment webhooks |
| [Operational Guides](https://developers.bead.xyz/reference-guide/operational-guides.md) | Supplemental production guidance such as webhook consumer design and wallet QA            |
| [Reporting](https://developers.bead.xyz/reporting.md)                                   | Search and review payment history across terminals, merchants, or partners                |
| [Settlement](https://developers.bead.xyz/settlement.md)                                 | Understand what settled for the merchant and what did not                                 |


---

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