# Payment Scenarios

## Payment Scenarios

### Purpose

Payment Scenarios explains how to handle non-happy-path outcomes after a payment has been created.

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 underpayment, overpayment, reclaimable balance, or return request.

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

* Go to [Payments](/payments.md) for payment creation, payment statuses, wallet flows, payment webhooks, receipts, and test transactions.
* Go to [Operational Guides](/reference-guide/operational-guides.md) for supplemental production guidance such as webhook hardening and wallet compatibility.
* Go to [Reporting](/reporting.md) and [Settlement](/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](/reference-guide/payment-scenarios/under-and-over-payment-handling.md)              | The customer sends less or more crypto than requested and the payment ends as `underpaid` or `overpaid`.                                  |
| [Reclaiming Unconverted Crypto](/reference-guide/payment-scenarios/reclaiming-unconverted-crypto.md)                   | A payment ends as `underpaid`, `overpaid`, `expired`, `invalid`, or `cancelled`, and unconverted funds must be reclaimed by the customer. |
| [Refunds for Crypto and Wallet Payments](/reference-guide/payment-scenarios/refunds-for-crypto-and-wallet-payments.md) | You need return-policy guidance for completed 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 `underpaid` or `overpaid`, open [Under- and Over-Payment Handling](/reference-guide/payment-scenarios/under-and-over-payment-handling.md).
3. If unconverted funds remain, open [Reclaiming Unconverted Crypto](/reference-guide/payment-scenarios/reclaiming-unconverted-crypto.md).
4. If the payment completed and the business wants to return funds afterward, open [Refunds for Crypto and Wallet Payments](/reference-guide/payment-scenarios/refunds-for-crypto-and-wallet-payments.md).
5. Apply the business handling in your UI, support workflow, and internal reconciliation process.

### Scenario routing guide

| Payment outcome                                                      | What it means for the business                                                                         |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `completed`                                                          | Payment succeeded. Follow your normal completed-payment workflow.                                      |
| `underpaid`                                                          | Do not fulfill. The customer must reclaim the funds and start a new payment if they still want to pay. |
| `overpaid`                                                           | Treat the requested amount as paid. Any excess is handled through reclaim.                             |
| `expired`                                                            | Do not fulfill. If funds later arrive and remain unconverted, they are handled through reclaim.        |
| `invalid`                                                            | Do not fulfill. Any eligible unconverted funds are handled through reclaim.                            |
| `cancelled`                                                          | Do not fulfill. Any remaining unconverted funds may be reclaimed.                                      |
| Customer wants money back after a completed crypto or wallet payment | Follow the refund or return guidance for completed payments, which is separate from reclaim.           |

### Related sections

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


---

# Agent Instructions: 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:

```
GET https://developers.bead.xyz/reference-guide/payment-scenarios.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.