Payment Scenarios

Purpose

The Payment Scenarios section walks you through non-happy-path situations that can occur after you create a payment. It explains how Bead surfaces each state, which webhooks fire, and what actions you—or the customer—should take next.

What you’ll find here

Page	When to read it
Under- and Over-payment Handling	Customer sends less or more crypto than requested and the payment flips to underpaid or overpaid.
Reclaiming Unconverted Crypto	A payment ends in a state (underpaid, overpaid, expired, invalid, cancelled) that leaves residual crypto the customer must reclaim.
(Coming soon) Refund Scenarios	Full and partial refunds, webhook events, and ledger impact.

How to use this section

1. Identify the status code your webhook reports (underpaid, completed, expired, etc.).

2. Open the matching scenario page for step-by-step guidance.

3. Implement the recommended webhook handling and UI prompts to give customers a smooth recovery path and minimize support tickets.

These scenarios complement the main Payments reference pages, filling in the “what happens if something goes wrong?” details you need for a robust integration.