Guide
Handle underpayments
What happens when a buyer sends too little, and what to deliver.
What happens when a buyer sends too little
Wallets and exchanges sometimes take their fee out of the amount sent, so a buyer can land a little short. When that happens, the checkout shows the exact amount still missing and the buyer can send it to the same address. While the payment is short, payment/lookup shows partial: 1 with received and remaining in the coin.
Payments expire an hour after they're created.
Accepting small shortfalls
In Settings → Payments you can accept underpayments up to a tolerance you choose (at most 50%). A payment that lands within it completes straight away:
- The webhook and the lookup say
COMPLETED, withunderpaid: true. amountis still the order total.amount_paidis what the buyer actually paid, in the order currency.- Your balance is credited the share that arrived, not the full order.
- A later refund is capped at what arrived.
{
"tid": "8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1",
"status": "COMPLETED",
"amount": "100.0000",
"currency": "USD",
"amount_paid": 96.5,
"underpaid": true,
"metadata": "order_4815",
"timestamp": 1781049600
}
What to deliver
Pick the rule that suits what you sell:
- Hold the order and ask the buyer to pay the rest, or refund what arrived. This is what our shop plugins do by default.
- Record a part payment of
amount_paidif your billing system supports it, and leave the rest due. - Deliver anyway for small gaps you're happy to absorb.
use CryptoPayr\Webhook;
if ($event['status'] === Webhook::STATUS_COMPLETED) {
if (Webhook::isUnderpaid($event)) {
holdOrder($event['metadata'], Webhook::amountPaid($event));
} else {
fulfilOrder($event['metadata']);
}
}const { Webhook } = require('cryptopayr');
if (event.status === Webhook.STATUS_COMPLETED) {
if (Webhook.isUnderpaid(event)) holdOrder(event.metadata, Webhook.amountPaid(event));
else fulfilOrder(event.metadata);
}from cryptopayr import webhook, STATUS_COMPLETED
if event["status"] == STATUS_COMPLETED:
if webhook.is_underpaid(event):
hold_order(event["metadata"], webhook.amount_paid(event))
else:
fulfil_order(event["metadata"])underpaid and amount_paid are missing, the payment was paid in full. Older code that ignores them keeps working, but it would deliver in full for a short payment, so update it if you accept underpayments.Overpayments
You're credited the order value. Anything the buyer sends on top is kept as credit for that buyer, which they can spend at a later checkout, so there's nothing for you to return.