Under- and Over-Payment Handling

If the customer sends less or more crypto than requested, Bead flags the payment with one of two status codes:

statusCode	What happened	Auto-conversion	Next step
underpaid	Amount received < amount requested	None – funds stay in the original asset	Customer must reclaim the unconverted amount
overpaid	Amount received > amount requested	Requested portion converts; excess stays unconverted	Customer must reclaim the excess

Bead never auto-tops-up an underpayment or auto-refunds an overpayment. The reclaim flow ensures all residual funds return to the customer.

What Bead Does Automatically

1. Sets the payment statusCode to underpaid or overpaid.

2. Emits a webhook with the full payment object.

3. If the customer entered an email (checkout or API request), sends instructions for reclaiming funds.

Integrator Workflow

Underpaid

1. Wait for the webhook (statusCode = underpaid).

2. Display “Payment incomplete – reclaim required” message in your UI.

3. Do not ask the customer to send a top-up; they must initiate a new payment.

4. Customer follows the email link to reclaim the original transfer.

Overpaid

1. Webhook arrives with statusCode = overpaid.

2. Confirm the requested amount has settled (amounts.settleableAmount).

3. Display “Excess received – reclaim required” message in your UI.

4. Customer follows the email link to reclaim the excess funds.

---

Best Practices Checklist

✔︎ Best Practice	Why
Listen for underpaid / overpaid via webhook instead of polling	Faster UI updates and fewer API calls
Surface a clear reclaim prompt (modal, banner, or email)	Minimizes support tickets about “where is my money?”
Instruct the customer to use Bead’s Claim Refund mechanism	Reduces merchant & integrator liability
Treat both events as terminal – start a fresh payment to complete the transaction	Maintains clean audit lineage
Log each occurrence with trackingId, received amount, and reclaim completion date	Helps reconcile outstanding liabilities