How a payment moves
Invoices, checkouts and payments, every status a checkout passes through, and what happens when a payer sends the wrong amount.
Three objects carry a payment:
- An invoice (
inv_…) is what is owed, in US dollars. It isopenuntil paid, thenpaid. - A checkout session (
cs_…) is the hosted page that collects an invoice, atpaywithvolume.com/cs_…. It records the payer's choice of coin and network, and moves through the statuses below. - A payment (
pay_…) is one transfer that arrived for a checkout. A checkout can have more than one: a payer who sends too little can top up.
Customers are made for you: a customer_email on the invoice or the checkout finds or
creates the customer (cus_…) for that address.
A checkout's statuses
| Status | What it means |
|---|---|
open | Created. The payer is choosing where they pay from and a coin. |
awaiting_payment | They chose: an address and an exact amount are issued, and their 30 minutes run. |
detected | A transfer to the address has been seen on the network. It does not count yet. |
confirming | It is gathering confirmations, and waiting for the custodian to accept it. |
paid | What arrived covers the invoice. Final. |
underpaid | What arrived falls short. The payer can top up to the same address. |
overpaid | More arrived than was due. Paid, with the extra credited too. |
expired | Nothing arrived in time. |
A checkout is open for 24 hours for the payer to choose how to pay. Once they choose,
they have 30 minutes to send it. If neither happens, the checkout expires and
invoice.expired is sent. The invoice itself stays open: open a new checkout for it
if the payer comes back.
When a payment counts
A transfer counts only once Volume's custodian has accepted it, and the custodian accepts it only after the network's own confirmations. The payer sees the confirmations as progress:
| Network | Confirmations |
|---|---|
| Bitcoin | 2 |
| Lightning | settled |
| Tron | 20 |
| BNB Smart Chain | 15 |
Nothing is paid before that, so invoice.paid never refers to money that a
reorganisation or a refused deposit can take back. A deposit the custodian refuses never
counts.
When the amount is wrong
Payers withdraw from exchanges, and exchanges round. Volume handles the common mistakes so you do not have to:
- A little short. Up to 1% or $0.50 short, whichever is smaller, still counts as paid. Volume covers the gap: you are credited the full price, less the fee.
- Further short. The checkout is
underpaid,invoice.underpaidsays what has arrived and what is still owed, and the payer's page asks them to send the rest to the same address. A top-up that brings the total within the tolerance pays the invoice. What arrived is credited to you either way; Volume holds nothing back for the payer. - Too much, or twice. The invoice is paid and
invoice.paidis sent as usual, theninvoice.overpaidsays how much extra came. All of it is credited to you. Refunding the payer, if you choose to, is between you and them. - Late. A transfer to an expired checkout's address within 7 days is still credited, at the price the payer was quoted.
- The wrong coin or network. Volume's people look at it. Coins sent on a network the address cannot receive on may not be recoverable.
What the payer sees
The checkout page asks where the payer is paying from first. For an exchange it shows
the coin, the network with the cheapest withdrawal, the address and the exact amount
to withdraw, with the exchange's withdrawal fee already added. The payer presses
I've sent it, watches the confirmations, and gets a receipt with a button back to
your success_url. Cancel payment takes them to your cancel_url.
In live mode Volume emails the payer a receipt. It remembers the last coin and network an email address used, so paying you again is quicker.