Payment options

Which assets and networks an invoice offers, how the exact amount is worked out, and where it must be sent.

Each entry in an invoice's payment_options is one way to pay it:

{
  "asset": "USDT@tron:nile",
  "symbol": "USDT",
  "network": "tron:nile",
  "network_name": "TRON Nile testnet (TRC20)",
  "amount_due": "30",
  "address": "T…",
  "address_derivation": { "scheme": "forwarder_v1", "…": "…" },
  "payment_uri": null
}

#Asset codes

An asset code is SYMBOL@network, where the network is a CAIP-2 chain id: USDT@tron:mainnet, USDT@eip155:56 (BNB Smart Chain), USDC@eip155:8453 (Base), BTC@bip122:testnet4. network_name is the network as exchanges name it ("TRON (TRC20)"), which is what payers look for on a withdrawal screen.

Which assets your invoices offer is up to you: pass assets when you create an invoice, or set default_assets once with POST /v1/merchant/settings. An asset your account cannot use is refused with asset_unavailable (the message says when it exists only in the other mode).

Your account offers the subset for the chains it has payout addresses on. Bitcoin is offered in test mode only for now. On Solana the checkout shows an address only when it is in your pins.

#The amount due

amount_due is exactly how much must arrive, as a decimal string in whole tokens.

• Stablecoins are priced 1:1 with their currency, and only in it: a USD invoice can be paid in USDT or USDC, a EUR invoice cannot (currency_unsupported). Amounts are scaled exactly; if a currency had more decimals than the token, the amount would be rounded up, never down.
• BTC is converted at the current price when the invoice is created, rounded up to the next satoshi, and fixed for the 15-minute price lock (see late payments).

An invoice with several options is one bill: a payer can pay part in one asset and the rest in another, and the parts add up (each converted to the asset the invoice is priced in, the first stablecoin you listed).

#The address

• TRON: each invoice gets an address of its own for TRON.
• EVM networks: each invoice gets one address, the same on every EVM network your account uses. A payment on the wrong one of those networks is still credited (wrong chain).
• Bitcoin: a fresh address from your own xpub for every invoice, never reused (Bitcoin with your xpub).

address_derivation tells the checkout how the address was made, so it can recompute it on the payer's device and refuse to show an address that does not pay you. See security model.

payment_uri is a wallet link where the network has a standard one: EIP-681 on EVM networks (ethereum:<token>@<chain>/transfer?address=…&uint256=…) and BIP-21 for Bitcoin. TRON and Solana have none: payment_uri is null.