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:
underpaidoverpaid
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
underpaidThe 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
overpaidThe 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:
underpaidoverpaidexpiredinvalidcancelled
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
underpaidRecommended next action:
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
overpaidRecommended next action:
mark the order or invoice as paid for the requested amount
continue the normal fulfillment flow
tell the customer the excess is handled separately
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
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 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 fulfilloverpaid: fulfill the original order amountcompleted: fulfill normallyother non-happy-path outcomes: follow the applicable reclaim or exception flow
Best practices
treat
underpaidandoverpaidas outcome-driven business states, not just technical statuseskeep reclaim handling separate from merchant refund handling
create a new payment for any retry after an
underpaidoutcomemake 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