Under and Over Payment Handling

In crypto wallet payment flows, the customer types the amount they send, so the amount received can differ from the amount requested. This page explains how to handle payments that end as overpaid or underpaid.

These two outcomes are handled differently. overpaid is a paid payment: fulfill the order. underpaid is a declined payment: do not fulfill, and offer the customer a new payment. Both are final statuses. Earlier versions of this guidance treated both as failed payments.

When this page applies

Use this page when the payment outcome is overpaid or underpaid.

If the payment ends as expired, invalid, or cancelled, use the reclaim guidance instead.

If the payment was paid and the customer later wants money back, use the refund and return guidance instead.

What these outcomes mean

Outcome	What happened	Paid?	What settles to the merchant	What goes back to the payer
overpaid	The customer sent more than the requested amount.	Yes	The requested amount	The excess, through reclaim
underpaid	The customer sent less than the requested amount.	No	Nothing	The full amount sent, through reclaim

A very small overpayment, within a per tender tolerance set by Bead, is classified as completed instead of overpaid. The payment settles normally and no reclaim is offered for the excess.

overpaid and underpaid are final statuses. statusCode does not change when the payer reclaims their funds. Reclaim progress is reported in refundLifecycleStatus, which reaches completed when the return is done. If the payer never reclaims, or the amount is below the minimum that can be returned, refundLifecycleStatus does not reach completed.

How to handle an overpaid payment

When a payment ends as overpaid:

• Fulfill the order, the same as for completed

• Mark the order or invoice as paid

• Do not ask the customer to pay again

• Tell the customer they sent more than requested and that the excess will be returned through Bead's reclaim process

• Expect later webhooks as the return of the excess progresses, with statusCode still overpaid. Keep the order fulfilled

The requested amount is batched and settled to the merchant like a completed payment. The excess is held separately and returned to the payer. It is not part of the merchant's settlement.

How to handle an underpaid payment

When a payment ends as underpaid:

• Do not fulfill the order

• Treat it like a declined payment. Nothing was processed for the order

• Do not ask the customer to send the difference to the same payment session. The session cannot be topped up

• Offer the customer a new payment, with the same tender or a different one

• Tell the customer the amount they sent will be returned through Bead's reclaim process

• Expect later webhooks as the return progresses, with statusCode still underpaid

Reclaim versus refund

Keep these flows separate.

Reclaim is how Bead returns crypto to the payer that was not part of a paid amount. It applies to the excess on overpaid, and to the full amount received on underpaid, expired, invalid, and cancelled. Bead runs the reclaim flow. Your integration does not.

Refund or return guidance applies when the merchant later decides to return value to the customer for a paid order, under its normal return policy. Bead has no refund endpoint.

A completed reclaim is not a merchant initiated refund. When the excess on an overpaid payment is returned, the order has not been returned.

Webhooks and status handling

Your integration should:

• Listen for payment status changes through webhooks

• Act on the first outcome for the payment: fulfill on overpaid, decline on underpaid

• Expect further webhooks as the reclaim progresses. Bead sends a payment webhook each time refundLifecycleStatus changes, with the payment's final statusCode unchanged

• Treat those later webhooks as record updates, not as a new fulfillment decision

• Avoid building merchant logic that assumes every customer will send the exact requested amount

See Tracking Reclaim Status for the reclaim fields and lifecycle values.

Customer messaging guidance

Clear customer messaging reduces support friction.

Suggested guidance for overpaid payments

Your payment was received and your order is confirmed. You sent more than the amount due, and the extra amount will be returned to you. Check your email for instructions to claim it.

Suggested guidance for underpaid payments

Your payment did not go through because the amount received was lower than the amount due. The amount you sent will be returned to you. Check your email for instructions to claim it. To complete your purchase, please start a new payment.

Fulfillment guidance

Payment outcome	Fulfillment behavior
completed	Fulfill normally
overpaid	Fulfill normally. The excess is returned to the payer
underpaid	Do not fulfill. Offer a new payment
expired, invalid, cancelled	Do not fulfill. Follow the applicable reclaim or exception flow

Best practices

• Fulfill on overpaid exactly as you do on completed

• Treat underpaid as a decline and create a new payment for any retry

• Keep reclaim handling separate from merchant refund handling

• Make your webhook processing idempotent, and expect reclaim progress events after the outcome

• Store the requested amount, the amount received, the outcome, and the order decision for support and reconciliation

Related pages

• Reclaiming Unconverted Crypto

• Tracking Reclaim Status

• Payment Statuses

• Payment Webhooks