Crypto payment links and invoices

How a crypto payment link works

1. The payee states what they are owed

   An asset, a network and an address — 500 USDT on TRC20, paid to their own wallet. That is your invoice record; SwapZilla never needs to know about it until the payer shows up.

2. The payer opens the link and picks a coin

   GET /v1/assets is the honest list of what can be paid with right now — every asset and network with at least one provider behind it. Render it as the picker.

3. Quote by the amount due, not by the amount sent

   This is the call that makes an invoice an invoice: ask amount_to=500 and the offer answers with the exact FromAmount the payer has to send. Add rate_type=fixed and that number stays true while they pay.

4. Open the order

   POST /v1/partner/orders with the offer, the payee's address as to_address, the payer's address as refund_address and your invoice number as client_order_id. Pass expected_to_amount and the order is refused rather than created if the payout drifted.

5. Show the address, then watch the order

   DepositAddress and AmountFrom are the whole payment page — as text, as a QR, with the network named. Poll GET /v1/partner/orders/{id} every 5–10 seconds until DONE, and the receipt is AmountToReceived plus TxID.

The two calls, in full

Quote a €500-sized invoice denominated in USDT, paid in BTC:

curl -sG "https://api.swapzilla.io/v1/partner/quotes" \
  -H "X-API-Key: $API_KEY" \
  --data-urlencode "from_asset=BTC" \
  --data-urlencode "from_network=BITCOIN" \
  --data-urlencode "to_asset=USDT" \
  --data-urlencode "to_network=TRC20" \
  --data-urlencode "amount_to=500" \
  --data-urlencode "rate_type=fixed"

The first offer is the best one. Turn it into a payable address:

curl -s -X POST "https://api.swapzilla.io/v1/partner/orders" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "offer_id": "0b0c8f0e-2c1a-4f3f-8f57-2a1d1c4e77aa",
    "to_address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "refund_address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
    "client_order_id": "INV-2026-0413",
    "expected_to_amount": 500
  }'

Then a loop that turns statuses into invoice states:

const terminal = ["DONE", "TIME_EXPIRED", "FAILED", "REFUNDED"];

async function watch(orderID) {
  for (;;) {
    const r = await fetch(`https://api.swapzilla.io/v1/partner/orders/${orderID}`, {
      headers: { "X-API-Key": process.env.API_KEY },
    });
    const order = await r.json();
    await onInvoiceState(order);                       // your own bookkeeping
    if (terminal.includes(order.Status)) return order;
    await new Promise((s) => setTimeout(s, 7000));     // 5–10 s is the right cadence
  }
}

Invoice states, mapped from order statuses

What this does not do

Who bills this way

• Freelancers invoicing across borders. The client pays in whatever they hold; the invoice is settled in USDT on the network the freelancer's wallet actually uses.
• Studios and agencies issuing milestone invoices, each one its own order and its own client_order_id.
• Platforms that bill on behalf of their users — the payee address is the user's, so the platform never holds client money and never becomes the party that owes it.
• Anyone billing a payer on another chain: the payer's BTC and the payee's TRC20 USDT never have to meet on the same network.

Questions