# Under and Over Payment Handling ## 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` * `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 a successful payment for the requested amount, with the excess handled separately through reclaim. ### 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`: * treat the requested amount as paid * continue your normal fulfillment flow for the original purchase * do not ask the customer to create a second payment for the same order * do not treat the excess amount as part of a merchant refund flow * direct the customer to reclaim any eligible unconverted excess #### Recommended business handling Your customer-facing messaging should make it clear that the original purchase amount was satisfied, but that any excess is handled separately. This helps avoid confusion where a customer expects the extra amount to stay attached to the order or expects a standard merchant refund flow for the overage. ### Reclaim versus refund It is important to keep these flows separate. #### Reclaim 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` * `cancelled` #### Refund or return 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` Recommended next action: 1. mark the order or invoice as unpaid or incomplete 2. stop fulfillment 3. tell the customer the payment did not complete for the requested amount 4. send the customer to reclaim guidance if applicable 5. generate a new payment if they still want to proceed #### For `overpaid` Recommended next action: 1. mark the order or invoice as paid for the requested amount 2. continue the normal fulfillment flow 3. tell the customer the excess is handled separately 4. send the customer to reclaim guidance if applicable ### 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 covered the requested amount. Any excess amount is handled separately through reclaim instructions associated with the payment. ### Fulfillment guidance Use the payment outcome to determine fulfillment. * `underpaid`: do not fulfill * `overpaid`: fulfill the original order amount * `completed`: fulfill normally * other non-happy-path outcomes: follow the applicable reclaim or exception flow ### Best practices * treat `underpaid` and `overpaid` as outcome-driven business states, not just technical statuses * keep reclaim handling separate from merchant refund handling * create a new payment for any retry after an `underpaid` 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) * [Refunds for Crypto and Wallet Payments](/reference-guide/payment-scenarios/refunds-for-crypto-and-wallet-payments.md) * [Payment Statuses](/payments/payment-statuses.md) * [Payment Webhooks](/payments/payment-webhooks.md) --- # Agent Instructions: 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: ``` GET https://developers.bead.xyz/reference-guide/payment-scenarios/under-and-over-payment-handling.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.