CryptoPayr Docs
Dashboard Get API key

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, with underpaid: true.
  • amount is still the order total. amount_paid is 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_paid if 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"])
If 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.