Under and Over Payment Handling
Some payment outcomes require follow-up before the merchant can decide whether to fulfill, close the order, or direct the customer to another flow. This page explains how to handle payments that end as underpaid or overpaid. These scenarios are most relevant in crypto wallet payment flows, where the customer controls the amount they send.
When this page applies
Use this page when the final payment outcome is underpaid or overpaid.
If the payment ends as expired, invalid, or cancelled, use the reclaim guidance instead.
If the payment completed successfully and the customer later wants money back, use the refund and return guidance instead.
What these outcomes mean
underpaid
The customer sent less than the requested amount. This should be treated as an incomplete payment. The merchant should not fulfill the order based on that payment.
overpaid
The customer sent more than the requested amount. This should be treated as an incomplete payment. The full crypto amount paid by the customer remains unconverted and is returned to the payer through Bead's reclaim process. No portion of an overpaid payment is converted or settled to the merchant.
How to handle an underpaid payment
When a payment ends as underpaid:
Do not fulfill the order
Do not treat the payment as complete
Do not ask the customer to continue using the same payment session
Direct the customer to reclaim any eligible unconverted funds
Create a new payment if the customer still wants to complete the purchase
Recommended business handling
Your support, checkout, or order management flow should clearly tell the customer that the payment did not complete successfully because the amount received was lower than the amount requested. If the customer still wants to proceed, generate a new payment and direct them to that new payment flow rather than trying to recover the original payment session.
How to handle an overpaid payment
When a payment ends as overpaid:
Do not fulfill the order
Do not treat the payment as complete
Do not ask the customer to continue using the same payment session
Direct the customer to reclaim the full unconverted amount
Create a new payment if the customer still wants to complete the purchase
Recommended business handling
Your customer-facing messaging should make it clear that the payment did not complete because the amount received exceeded the amount requested. The full crypto amount will be returned through Bead's reclaim process. If the customer still wants to proceed, generate a new payment and direct them to a new payment flow.
Reclaim versus refund
It is important to keep these flows separate.
Reclaim applies when a payment does not settle cleanly as intended and unconverted funds remain associated with the payment outcome. This is the correct follow-up for underpaid, overpaid, expired, invalid, and cancelled.
Refund or return guidance applies only after a completed payment, when the merchant later decides to return value to the customer under its normal return policy. Do not treat underpaid or overpaid handling as the same thing as a post-payment refund.
Integration guidance
Your integration should use the payment outcome to decide what happens next.
For underpaid
Mark the order or invoice as unpaid or incomplete
Stop fulfillment
Tell the customer the payment did not complete for the requested amount
Send the customer to reclaim guidance if applicable
Generate a new payment if they still want to proceed
For overpaid
Mark the order or invoice as unpaid or incomplete
Stop fulfillment
Tell the customer the payment did not complete because the amount received exceeded the amount requested
Send the customer to reclaim guidance so the full unconverted amount can be returned
Generate a new payment if they still want to proceed
Webhooks and status handling
Use the final payment outcome as the source of truth for your workflow. In practice, that means your integration should:
Listen for payment status changes through webhooks
Update your internal order or invoice state when the payment becomes
underpaidoroverpaidAvoid building merchant logic that assumes every customer will send the exact requested amount
For operational follow-up or support workflows, you can also retrieve the latest payment record directly when needed.
Customer messaging guidance
Clear customer messaging reduces support friction.
Suggested guidance for underpaid payments
Your payment did not complete because the amount received was lower than the amount requested. Please follow the reclaim instructions for the original transfer. If you still want to complete your purchase, start a new payment.
Suggested guidance for overpaid payments
Your payment did not complete because the amount received was higher than the amount requested. The full amount you sent will be returned through the reclaim process. If you still want to complete your purchase, start a new payment.
Fulfillment guidance
Use the payment outcome to determine fulfillment.
underpaid
Do not fulfill
overpaid
Do not fulfill
completed
Fulfill normally
expired, invalid, cancelled
Do not fulfill. Follow the applicable reclaim or exception flow.
Best practices
Treat
underpaidandoverpaidas non-successful final states that both require reclaim and a new payment to retryKeep reclaim handling separate from merchant refund handling
Create a new payment for any retry after an
underpaidoroverpaidoutcomeMake your webhook processing idempotent
Store the requested amount, final outcome, and order decision in your internal records for support and reconciliation
Related pages
Last updated