> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/reference-guide/payment-scenarios/under-and-over-payment-handling.md). # 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 `underpaid` or `overpaid` * Avoid 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. | Payment outcome | Fulfillment behavior | | --------------------------------- | ---------------------------------------------------------------- | | `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 `underpaid` and `overpaid` as non-successful final states that both require reclaim and a new payment to retry * Keep reclaim handling separate from merchant refund handling * Create a new payment for any retry after an `underpaid` or `overpaid` outcome * Make your webhook processing idempotent * Store the requested amount, final outcome, and order decision in your internal records for support and reconciliation ### Related pages * [Reclaiming Unconverted Crypto](/reference-guide/payment-scenarios/reclaiming-unconverted-crypto.md) * [Payment Statuses](/payments/payment-statuses.md) * [Payment Webhooks](/payments/payment-webhooks.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/reference-guide/payment-scenarios/under-and-over-payment-handling.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.