Amounts & currencies
Use exact decimal strings and distinguish requested amounts, recipient transfers, and merchant debits.
All monetary values and rates are decimal strings. Preserve the strings or use an exact decimal library. Converting them to JavaScript Number, parseFloat, or binary floating point can lose precision.
Decimal strings#
{ "amount": "0.000000000000000001", "currency": "ETH", "network": "ethereum" }Do not use exponential notation, thousands separators, or a localized decimal comma. Amounts must be positive where a request requires a transfer or payment. Maximum precision depends on the selected pair's decimals, or on the fiat denomination's minor units. Excess precision is rejected; it is not safe to rely on rounding.
The exact status/code for a precision refusal depends on the operation. Invoice validation can return 400 validation_error; outgoing-payment validation commonly returns 422 unprocessable_entity.
Currency and network#
Use both currency and network for crypto requests, even for BTC or another single-network asset. Get the pair from the currency catalog. A ticker alone does not identify the network.
Fiat invoice prices use an enabled denomination, such as USD or EUR, without network. The customer chooses a crypto payment pair on checkout. See fiat invoice prices.
Invoice amounts#
When creating an invoice, send amount, currency, and, for crypto prices, network. The API returns that original price under different names: amount becomes nominal_amount, currency becomes nominal_currency, and network becomes nominal_network (null for fiat). Do not send nominal_* in the request.
Every field in the table below belongs to the invoice response. Its currency and network describe the customer's crypto payment, even when the request's currency was USD or EUR. See the request-to-response example.
| Response field | Meaning |
|---|---|
nominal_amount, nominal_currency, nominal_network | The original invoice price and denomination returned by the API; nominal_network is null for fiat prices |
amount_requested | The selected crypto payment total, including any fees paid by the customer; null before checkout selection |
currency, network | The crypto payment pair; fixed for a crypto-priced invoice, initially null for a fiat-priced invoice |
amount_paid | Cumulative accepted gross payment amount, not an available balance or net credit |
payments[].amount | The observed transfer amount; its payment status alone does not prove that funds have been accepted |
payments[].settlement | That one payment's own ledger facts and conversion state; null where the read did not compute them. See payment settlement |
Even payments[].status: confirmed does not prove merchant credit: blockchain confirmation and financial acceptance are separate steps. Use invoice amount_paid and acceptance events to track accepted gross payments, the invoice status for fulfillment, and the balances endpoint for spendable funds. A payment's confirming status tracks blockchain confirmations; the invoice's confirming status indicates accepted partial funds.
Settlement amounts are that payment's own native figures. settlement.accepted_source_amount, settlement.source_available_contribution and settlement.credited_target_amount are decimal strings in the gate they were booked in, and source_available_contribution is signed. Do not sum them with another payment's, with amount_paid, or across currencies and networks.
Payout and refund amounts#
The following fields describe payouts and refunds.
| Field | Meaning | Where |
|---|---|---|
amount | Requested principal | Payout, refund |
recipient_amount | Amount actually sent after customer-allocated commercial charges | Payout, refund |
target_funding_amount | Target-denominated obligation of the payout; not a debit in any source currency | Payout |
balance_movements | Effect on every participating currency and network, including gates with zero net effect | Payout |
merchant_debit_amount | Total merchant debit including merchant-allocated commercial charges | Refund |
fee_amount / refund_fee | Configured service fee in the payout/refund currency | Payout, refund |
configured_network_fee_amount | Snapshotted commercial network charge in the payout/refund currency | Payout, refund |
network_fee | Measured on-chain cost, nullable before measurement; a separate figure from the commercial network charge | Payout, refund |
A payout has no single scalar merchant debit: it can be funded from other balances, so its effects are reported per currency and network in balance_movements, with funding describing each source. funding is null for a source-free payout. Historical payouts without an accepted commercial snapshot report economics_status: "unavailable" with null recipient, obligation and fee amounts. See payout funding.
Fee allocation can be customer, merchant, or platform. Do not assume the requested amount, recipient amount, and the amount charged are equal. Do not add the actual network_fee again to the payout's target_funding_amount or to a refund's merchant_debit_amount.
The actual network cost may be in a gas currency different from the transfer currency. Payout responses include network_fee_currency and network_fee_network. Refund REST responses currently omit those denomination fields; the refund.completed event includes them. Do not guess a refund's fee currency from its transfer currency.
Webhook money fields#
Invoice acceptance events describe one payment in the invoice's currency and network: gross_amount is its contribution, fee_total is the amount withheld for that acceptance, and net_amount = gross_amount - fee_total. Withheld charges include the service fee, payer-priced conversion spread and any recovery fee. Platform-paid service fees are excluded from fee_total.
For a recovered payment in another asset, these fields are invoice-equivalent values calculated using frozen prices. They do not represent an exchange or a balance credit in the invoice asset. late_payment_amount follows the same rule. Read the invoice's payments[] for each actual source amount and network, and its settlement for credited funds and charges. Refunds use the selected payment's actual asset and network.
A late acceptance can emit both invoice.late_payment and invoice.paid with different event IDs. Do not sum event credits. Reconcile the invoice's current cumulative amount_paid, and treat net balances separately. A reversal reduces accepted gross and may change the invoice status; reversed_amount is not necessarily the exact net debit to reproduce in your own ledger.