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	What this means for the integrator
underpaid	Amount received < amount requested	None, funds stay in the original asset	Treat as not successful payment. Do not fulfill. If the customer still wants to pay, start a new payment. Customer reclaims the full amount sent.
overpaid	Amount received > amount requested	Requested portion converts	Treat as successful payment for the requested amount. You may fulfill once confirmed. Customer reclaims only the overage.

Bead never adds more funds to complete an underpayment and never processes refunds for an overpayment inside the original payment. Any unconverted value is returned through the reclaim flow so that remaining crypto goes back to the payer.

What Bead does automatically

1. Sets the payment statusCode to underpaid or overpaid.

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

3. Sends reclaim instructions by email once an email address is available.

   • In digital or virtual flows, the email typically comes from the original payment request payload.

   • In physical or terminal based flows, customer email is often not provided. In underpaid and overpaid outcomes, the hosted payment page prompts the customer to enter an email address, then Bead sends reclaim instructions.

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 (or retrieve the status using the tracking endpoint).

2. Treat the payment as not successful.

   • Do not fulfill the order.

   • Do not record this payment as settled.

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

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

4. Inform the customer that the crypto they sent will be returned via reclaim.

   • Bead returns the full amount received in the original asset through the reclaim process.

   • If an email was provided in the original request, Bead emails the reclaim instructions.

   • If no email was provided, the hosted payment page prompts for an email address and then Bead emails the reclaim instructions.

Overpaid

1. Wait for the webhook with statusCode = overpaid (or retrieve the status using the tracking endpoint).

2. Treat the payment as successful for the requested amount.

   • The requested portion will be processed and settled.

   • You may proceed with fulfillment once your system confirms the final state.

3. Confirm the settleable value for your records.

   • Use amounts.settleableAmount to confirm the portion that will settle.

4. Inform the customer that the extra amount will be returned via reclaim.

   • Bead returns only the overage in the original asset through the reclaim process.

   • If an email was provided in the original request, Bead emails the reclaim instructions.

   • If no email was provided, the hosted payment page prompts for an email address and then Bead emails the reclaim instructions.

In both cases, direct the customer to a fresh payment if they still need to complete a purchase, and rely on Bead’s reclaim flow for any return of crypto.

Suggested UI messaging

You can adapt the wording below for your checkout UI or support workflows.

Underpaid message

Payment not completed. The amount sent was less than requested. Your crypto will be returned using Bead’s reclaim process. Please start a new payment to try again.

Overpaid message

Payment completed for the requested amount. An extra amount was received and will be returned using Bead’s reclaim process.

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.

  • Underpaid: no portion is settled.

  • Overpaid: the requested portion is settled.

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 what portion 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.

✔ Treat underpaid as not successful Do not fulfill. Create a new payment for any retry.

✔ Treat overpaid as successful for the requested amount Fulfill based on the requested amount once confirmed. Do not attempt to refund the difference yourself.

✔ Surface a clear reclaim prompt Use a banner, modal, or in app message that explains that reclaim instructions are 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 returns in your own ledger.

✔ Log each occurrence Store at least:

• trackingId

• Amount requested

• Amount received

• Status (underpaid or overpaid)

• Settleable amount when overpaid

• Reclaim completion date if available

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