Ссылки на оплату и инвойсы в криптовалюте

Как устроена ссылка на оплату

1. Получатель указывает, что ему должны

   Актив, сеть и адрес — 500 USDT в сети TRC20 на собственный кошелёк. Это ваша запись о счёте; SwapZilla узнаёт о ней только в момент, когда появляется плательщик.

2. Плательщик открывает ссылку и выбирает монету

   GET /v1/assets — честный список того, чем можно заплатить прямо сейчас: активы и сети, за которыми стоит хотя бы один провайдер. Из него и рисуется выбор.

3. Котировка по сумме счёта, а не по сумме отправки

   Именно этот вызов превращает обмен в инвойс: запрашиваете amount_to=500 — и предложение отвечает точной суммой FromAmount, которую нужно отправить. Добавьте rate_type=fixed, и это число не изменится, пока идёт оплата.

4. Создание ордера

   POST /v1/partner/orders: предложение, адрес получателя в to_address, адрес плательщика в refund_address, ваш номер счёта в client_order_id. Передайте expected_to_amount — и ордер будет отклонён, а не создан, если выплата успела «уехать».

5. Показать адрес и следить за ордером

   DepositAddress и AmountFrom — это и есть вся страница оплаты: текстом, QR-кодом и с явно названной сетью. Опрашивайте GET /v1/partner/orders/{id} раз в 5–10 секунд до DONE; квитанция — это AmountToReceived и TxID.

Оба вызова целиком

Котировка счёта на 500 USDT, оплачиваемого в 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"

Первое предложение — лучшее. Превращаем его в адрес для оплаты:

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
  }'

И цикл, который переводит статусы ордера в состояния счёта:

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);                       // ваш собственный учёт
    if (terminal.includes(order.Status)) return order;
    await new Promise((s) => setTimeout(s, 7000));     // 5–10 с — правильный ритм
  }
}

Состояния счёта в терминах статусов ордера

Чего здесь нет

Кто так выставляет счета

• Фрилансеры, работающие с зарубежными заказчиками. Клиент платит тем, что у него есть; счёт закрывается в USDT в той сети, которой действительно пользуется кошелёк исполнителя.
• Студии и агентства со счетами по этапам: каждый этап — свой ордер и свой client_order_id.
• Платформы, выставляющие счета от имени своих пользователей: адрес получателя — пользовательский, поэтому платформа не держит клиентские деньги и не становится должником по ним.
• Все, кому платят из другой сети: BTC плательщика и USDT TRC20 получателя не обязаны встречаться в одном блокчейне.

Вопросы