easyway
Log inGet started

Handle underpaid and late crypto payments

With crypto the customer sends the money, not you, so the amount and the timing are theirs. Some wallets subtract the network fee from the amount, some customers pay from an exchange hours later, some send twice. This guide shows what easyway does in each case and what your order logic should do about it.

The rules in one table

An invoice's coin amount (pay_amount) is fixed when the coin is chosen. Every payment to your wallet that belongs to the invoice is compared with it once it has the coin's confirmations. The money itself goes straight to your wallet, in full: easyway takes no fee from it and never holds it, so the table below is about statuses and events, not about where the coins are.

What the customer didInvoice statusWebhookOn the invoice
Sent the full amount (or within your tolerance)paidinvoice.paidreceived_amount = what arrived
Sent lessunderpaidinvoice.underpaidremaining_amount = what is missing
Sent the rest laterpaidinvoice.paidreceived_amount = both payments
Sent morepaidinvoice.paid and invoice.overpaidoverpaid_amount = the excess
Paid again after it was paidpaid (unchanged)invoice.overpaidreceived_amount and overpaid_amount grow
Paid nothing before expires_atexpiredinvoice.expiredNothing
Paid after expiry, while still watchedpaid or underpaidinvoice.paid or invoice.underpaidlate: true
Paid after you cancelled itcancelled (unchanged)None — you get an e-mailreceived_amount grows, late: true

Each short payment sends its own invoice.underpaid, so one invoice can produce several. Before the confirmations are in, a pending invoice shows confirming and you get invoice.confirming — that is not money yet.

On TRON, EVM chains and Solana your wallet has one address and the exact amount identifies the invoice, so a payment that is off by more than your tolerance can only be tied to the invoice when it is the only open one on that address. On TON and XRP the memo or destination tag identifies it; on Bitcoin-like chains with an extended public key, the fresh address does.

Underpayment tolerance

In Dashboard → Settings, Underpayment tolerance (0 %, 0.5 %, 1 %, 2 %, 3 % or 5 %; 1 % by default) decides how short a payment may be and still count as paid. It exists because many wallets and exchanges deduct their withdrawal fee from the amount the customer typed. With 1 %, a 100 USDT invoice that receives 99.2 USDT is paid; with 0 % it is underpaid and asks the customer for 0.8 USDT more. A paid invoice inside the tolerance keeps a small remaining_amount, so always decide on status.

When a customer underpays

The payment page switches to "send the remaining amount" with the missing figure and the same address (and the same memo or tag on TON and XRP). If Email me about underpayments is on in Settings, you get an email with what arrived and what is still owed, sent to the API key's support address, your support address or your account email. An underpaid invoice never expires: it stays underpaid until it is topped up, and a top-up is picked up as long as the invoice is still watched (see late payments below). One common cause is an exchange that took its withdrawal fee off the amount (see paying from an exchange). Your options:

PolicyWhen it fits
Wait for the top-up, then fulfil on invoice.paidThe default for physical goods and anything you cannot take back.
Fulfil partly (credit the customer what arrived)Account top-ups, prepaid credit, donations.
Return the moneyThe money is in your wallet, so you refund it yourself: send it from your wallet to an address the customer gives you. easyway cannot move, reverse or refund a payment.

Late payments

An invoice expires after its lifetime (60 minutes unless you set it per invoice or in Settings). If the customer had already chosen a coin, the invoice stays watched after expires_at: for 7 days on a fresh address derived from your extended public key (Bitcoin, Litecoin, Dogecoin, Dash), and for a few hours on a shared address, where its exact amount or memo stays reserved for it. A payment in that window turns the expired invoice paid or underpaid with late: true and the normal webhook — so an expired order is not a dead order. Release reserved stock on invoice.expired, but keep the order and accept a later invoice.paid. The coin amount does not change after expiry, even if the price has moved.

A cancelled invoice is different: cancelling was your decision, so it stays cancelled. A payment that still arrives (the address or amount is watched for a while after you cancel) is recorded on the invoice and flagged late: true, but no invoice.* webhook is sent; you get an e-mail instead, whatever your underpayment e-mail setting. The coins are already in your wallet: ship the order after all, or refund the customer or re-invoice them from your side. A payment after the watch window is not tied to the invoice automatically; the money is still in your wallet.

Payments that match no invoice

When a live transfer to your wallet cannot be tied to exactly one invoice — a missing or unknown memo on TON or XRP, an amount that fits no open invoice or fits several — easyway does not guess. It records an unmatched transaction, sends transaction.unmatched and lists it in the dashboard (and at GET /v1/transactions/unmatched, scope transactions:read). Assign it to an invoice in the same coin and it counts exactly like a matched payment, with the same webhooks; or ignore it. The coins are in your wallet either way.

A handler that covers every case

Events can arrive out of order and more than once, so the handler looks at the invoice's current status, never moves a fulfilled order backwards and remembers event ids. Save the invoice id on your order when you create it.

Node.js

// Runs after the signature check (see the webhook signatures guide).
async function handleInvoiceEvent(event) {
  if (await db.seenEvent(event.id)) return;            // a retry repeats the same event id
  const inv = event.data.invoice;
  if (!inv) return;                                     // transaction.unmatched and webhook.test carry no invoice
  const order = await db.orderByInvoiceId(inv.id);      // the id you saved when you created it
  if (!order) return;

  // Decide on the status, never on remaining_amount: an invoice paid within your
  // tolerance is "paid" with a small remaining_amount left.
  if (inv.status === "paid" && order.state !== "fulfilled") {
    if (order.state === "cancelled") {
      // Paid after you gave up on the order (inv.late is true): the money is already
      // in your wallet. Ship it anyway, or refund it from your wallet - never ignore it.
      await db.flagForReview(order.id, "paid_after_cancel", inv.received_amount);
    } else {
      await db.fulfil(order.id);                        // exactly once: state becomes "fulfilled"
    }
  } else if (inv.status === "underpaid" && order.state !== "fulfilled") {
    await db.setOrderState(order.id, "underpaid", { received: inv.received_amount, missing: inv.remaining_amount });
  } else if (event.type === "invoice.expired" && order.state === "open") {
    await db.releaseStock(order.id);                    // keep the order: a late payment may still come
  }
  await db.rememberEvent(event.id);
}

When an old order is in doubt, read the invoice again instead of trusting a stored webhook:

// Re-read an invoice before acting on an old order; received_amount is the total received, late says it came after expiry
const res = await fetch("https://api.easyway.cash/v1/invoices/inv_7Q2mN4kL8pR1sT9uV3wX0y", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.EASYWAY_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`easyway ${res.status}: ${(await res.json()).error}`);
const data = await res.json();

Test each case before going live

In test mode, Simulate payment on a test invoice accepts an amount: enter less than due for an underpayment, press again with the field empty for the top-up, enter more than due for an overpayment, and simulate on an expired invoice for a late payment. Unmatched transactions only exist in live mode. The sandbox guide has the full test plan, the webhook signatures guide the signature check that runs before this handler, and the API reference every status and field.

Create free accountRead the API docsAlready have an account? Sign in
Handle underpaid and late crypto payments | easyway