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.

Status outcomes

statusCode	What happened	Auto conversion	Next step
underpaid	Amount received < amount requested	None; funds stay in asset	Customer reclaims the full amount
overpaid	Amount received > amount requested	Requested portion converts	Customer reclaims the excess

Bead never adds more funds to complete an underpayment and never auto refunds an overpayment. Any residual funds are returned through the reclaim flow so that all remaining value goes back to the customer.

What Bead does automatically

1. Sets the payment statusCode to underpaid or overpaid.

2. Emits a webhook that includes the full payment object.

3. If the customer has an email on file, sends reclaim instructions by email.

   • Email can come from the original payment request payload or from the hosted page if the customer enters it there.

These actions happen regardless of how you created the payment, as long as Bead can associate a valid email address with the payment.

Integrator workflow

Underpaid

1. Wait for the webhook with statusCode = underpaid.

2. In your UI, clearly indicate that the payment is incomplete and that reclaim is required.

3. Do not ask the customer to send more crypto on the same payment.

   • If they still want to pay, create a new payment and send them to that new hosted page.

4. The customer follows the reclaim link in the email to retrieve the original transfer.

Overpaid

1. Wait for the webhook with statusCode = overpaid.

2. Confirm that the requested amount has a settled value using amounts.settleableAmount.

3. In your UI, indicate that an excess was received and that reclaim is required for the remainder.

4. The customer follows the reclaim link in the email to retrieve the excess funds.

In both cases, treat the existing payment as finished from a business perspective and direct the customer to a fresh payment if they still need to complete the purchase.

How this appears in Reporting and Settlement

• In Reporting (Partner, Merchant, and Terminal Payments), these payments appear with statusCode = underpaid or statusCode = overpaid.

• In Settlement, only the portion that is actually settled appears in settlement records. The reclaimable portion always remains unconverted and does not enter merchant settlement batches.

Use Reporting to see the original payment and its final status, and use the Settlement APIs to understand which part of the original amount, if any, was settled for the merchant.

Best practices checklist

✔︎ Listen for underpaid and overpaid via webhook Use webhooks instead of polling for faster UI updates and fewer API calls.

✔︎ Surface a clear reclaim prompt Use a banner, modal, or in app message that explains that funds are safe and that reclaim instructions were sent by email.

✔︎ Direct customers to Bead’s reclaim flow Instruct customers to use the reclaim link provided by Bead rather than trying to handle refunds in your own ledger. This reduces your operational and compliance burden.

✔︎ Treat both events as terminal for that payment Do not try to repair the same payment by topping up or partially refunding in place. Start a fresh payment for any further attempts so audit history remains easy to follow.

✔︎ Log each occurrence Store at least:

• trackingId

• Amount requested

• Amount received

• Status (underpaid or overpaid)

• Reclaim completion date if available

This helps reconcile outstanding liabilities and answer customer or auditor questions later.