Инвойсы¶

Инвойс — это запрос на оплату, привязанный к одному заказу. При его создании за инвойсом закрепляется депозитный адрес в выбранной вами сети, и всё, что придёт на этот адрес, засчитывается именно ему и никакому другому.

Создание инвойса¶

curl -X POST https://api.pay.nullswap.com/api/v1/invoices \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
        "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
        "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
        "expectedAmount": "25500000",
        "expiresInSeconds": 3600,
        "externalId": "order-10241"
      }'

Поля merchantId здесь нет: мерчанта уже определяет ваш API-ключ.

В ответе приходит сам инвойс:

{
  "id": "b2f4a6c8-0d1e-4f23-9a45-6b7c8d9e0f11",
  "merchantId": "9f1d2c3b-4a5e-4f60-8b71-2c3d4e5f6a7b",
  "depositWalletId": "7e2a9c14-8b3d-4c56-a789-0f1e2d3c4b5a",
  "depositAddress": "TQ5s...9Xk2",
  "depositTag": null,
  "depositXAddress": null,
  "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
  "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
  "expectedAmount": "25500000",
  "acceptsAnyToken": false,
  "autoSweep": true,
  "paidAmount": "0",
  "pendingAmount": "0",
  "externalId": "order-10241",
  "status": "WAITING",
  "amlStatus": null,
  "createdAt": "2026-01-01T12:00:00.000Z",
  "expiresAt": "2026-01-01T13:00:00.000Z",
  "updatedAt": "2026-01-01T12:00:00.000Z"
}

Покажите покупателю depositAddress и точную сумму expectedAmount, а после наступления expiresAt уберите их с экрана. На RIPPLE вместе с ними покажите depositTag с пометкой «обязательно»: там один адрес инвойс не определяет. См. Тег назначения на RIPPLE. На всех остальных сетях depositTag и depositXAddress равны null.

Ошибки¶

Проверки идут именно в таком порядке, так что вы получите ошибку по первому нарушенному правилу:

Тег назначения на RIPPLE¶

На RIPPLE, то есть в XRP Ledger, депозитный адрес принадлежит не только вам. Все инвойсы RIPPLE оплачиваются на один и тот же depositAddress, а к своему инвойсу платёж привязывается по тегу назначения (destination tag), который он несёт, и больше ни по чему. Этот тег инвойс называет в двух дополнительных полях:

{
  "id": "b2f4a6c8-0d1e-4f23-9a45-6b7c8d9e0f11",
  "depositWalletId": "7e2a9c14-8b3d-4c56-a789-0f1e2d3c4b5a",
  "depositAddress": "rHsMGQEkVNJmpGWs8XUBoTBiAAbwxZN5v3",
  "depositTag": 959725,
  "depositXAddress": "XVMFQQBMhdouRqhPMuawgBMN1AVFToG5NjwwoxoAYuiUyDF",
  "expectedAmount": "25000000",
  "status": "WAITING"
}

Покажите покупателю адрес, тег — подписанный как обязательный, а не как необязательная заметка, — и точную сумму. Можно показать и depositXAddress как альтернативу паре; именно его и стоит закладывать в QR-код: кошелёк, который его отсканирует, получит адрес и тег вместе. Оба поля есть и в data каждого вебхука invoice.*.

Засчитывается то, что платёж доставил на адрес, а не сумма, которая в нём указана: в XRP Ledger платёж можно отправить как частичный (partial payment), и считается только то, что дошло. Дальше недоплата и переплата работают как в любой другой сети — см. Недоплата и переплата.

Чтение инвойсов¶

GET /api/v1/invoices фильтрует по id, chainId, tokenId, status и externalId — каждый из них принимает несколько значений — плюс offset, limit, order и sortBy (CREATED_AT, EXPIRES_AT, ID).

GET /api/v1/invoices?status=PAID&status=PARTIALLY_PAID&limit=100&sortBy=EXPIRES_AT&order=ASC

Жизненный цикл статусов¶

stateDiagram-v2
    direction LR
    [*] --> WAITING

    WAITING --> PAYMENT_DETECTED
    WAITING --> PARTIALLY_PAID
    WAITING --> PAID
    WAITING --> EXPIRED

    PAYMENT_DETECTED --> WAITING
    PAYMENT_DETECTED --> PARTIALLY_PAID
    PAYMENT_DETECTED --> PAID
    PAYMENT_DETECTED --> EXPIRED

    PARTIALLY_PAID --> WAITING
    PARTIALLY_PAID --> PAYMENT_DETECTED
    PARTIALLY_PAID --> PAID
    PARTIALLY_PAID --> EXPIRED

    PAID --> WAITING
    PAID --> PAYMENT_DETECTED
    PAID --> PARTIALLY_PAID

    WAITING --> SWAPPING
    PAYMENT_DETECTED --> SWAPPING
    PARTIALLY_PAID --> SWAPPING
    PAID --> SWAPPING
    SWAPPING --> COMPLETED
    SWAPPING --> FAILED
    FAILED --> SWAPPING
    FAILED --> COMPLETED

    COMPLETED --> [*]
    EXPIRED --> [*]

Четыре детали на диаграмме легко не заметить:

• Статус может откатываться назад, в том числе из PAID. Транзакция, вытесненная реоргом, забирает свою сумму с собой: инвойс возвращается из PARTIALLY_PAID обратно в WAITING, а инвойс в PAID — в WAITING, PAYMENT_DETECTED или PARTIALLY_PAID, смотря по оставшимся суммам. Поэтому обработчик должен считать тело каждого вебхука снимком текущего состояния, а не приращением к предыдущему.
• Вперёд из PAID ведёт единственный путь — в SWAPPING. Пока инвойс оплачен, он не истечёт, а деньги, пришедшие в это время, запишутся как неожиданный платёж и на paidAmount не повлияют. Вывести инвойс из PAID может только откат платежа; после начала свипа откат платежа статус назад уже не двигает.
• SWAPPING, COMPLETED и FAILED следуют за свипами, а не за оплатой. Автоматический свип переводит инвойс из PAID в SWAPPING, когда свип принят; частично оплаченный инвойс продолжает ждать остаток. Ваш собственный вызов эндпоинта свипа переводит инвойс в SWAPPING, как только вызов отправил деньги в путь, — из WAITING, PAYMENT_DETECTED и PARTIALLY_PAID так же, как из PAID. В обоих случаях инвойс становится COMPLETED, когда ни один свип адреса не идёт и не провалился; оставшуюся на нём пыль никто не ждёт.
• FAILED — не конец. Когда свип инвойса в SWAPPING сдаётся после всех повторов, инвойс становится FAILED, и вы получаете invoice.failed. Деньги всё ещё на депозитном адресе: следующий свип — автоматический или запрошенный вами — возвращает инвойс в SWAPPING или сразу в COMPLETED, когда зачисляется.

COMPLETED и EXPIRED — терминальные состояния. Суммы после этого ещё могут уточняться, поэтому запоздавшая транзакция по истёкшему инвойсу будет записана, а не потеряна, — но статус уже не изменится.

Две суммы¶

pendingAmount и paidAmount меняются независимо друг от друга и означают разное.

На обе суммы влияют только платежи в той сети и в том токене, которые указаны в инвойсе. Депозиты в другом токене — никогда, что бы вы потом с ними ни решили делать. Статус выводится уже из этих двух величин:

paidAmount >= expectedAmount   -> PAID
paidAmount > 0                 -> PARTIALLY_PAID
pendingAmount > 0              -> PAYMENT_DETECTED
иначе                          -> WAITING

Недоплата и переплата¶

Неверную сумму инвойс не отклоняет — он записывает ровно то, что пришло.

Недоплата. Инвойс остаётся в PARTIALLY_PAID. Покупатель может доплатить до expiresAt, несколько депозитов складываются. Если срок вышел, а суммы так и не хватило, инвойс закрывается с уже записанным paidAmount: деньги не потеряны, но инвойс закрыт, и что делать дальше — решать вам.

Переплата. Инвойс переходит в PAID с paidAmount > expectedAmount. Верхней границы нет, статуса OVERPAID нет, автоматического возврата тоже. Хотите вернуть разницу — сравнивайте эти две суммы сами.

Истечение срока¶

Инвойс истекает по наступлении expiresAt — но не тогда, когда деньги ещё в пути. Срок не сработает, если у инвойса есть хотя бы один депозит, ждущий подтверждения, или хотя бы один подтверждённый депозит в альтернативном токене. Поэтому покупатель, заплативший незадолго до дедлайна, не потеряет платёж из-за того, что подтверждение пришло уже после него.

А вот инвойс в статусе PARTIALLY_PAID истечь может. Частичная оплата останавливает часы только на то время, пока что-то ещё подтверждается.

Альтернативные токены¶

Поставьте acceptsAnyToken: true — и депозит в другом токене совместимой сети будет записан как платёж ALTERNATIVE, а не признан ошибкой. В paidAmount он всё равно не попадёт: expectedAmount выражен в собственном токене инвойса, так что сколько такой депозит стоит и оплачен ли заказ — решаете вы.

Оставите false (значение по умолчанию) — тот же депозит станет платежом UNEXPECTED. Деньги записываются и там, и там; флаг меняет только их классификацию и то, спросят ли у вас решение по ним. См. Платежи по инвойсу.

Перевод средств на баланс¶

Деньги, оплаченные по инвойсу, приходят на его депозитный адрес. На ваш баланс — и в число того, что можно вывести, — они попадают, только когда их свипнут с этого адреса. Свип забирает всю чистую сумму одного токена на адресе разом, так что несколько платежей в одном токене переезжают вместе.

Кто запускает свип, решает флаг autoSweep у инвойса:

Свипается каждый платёж, который подтвердился и прошёл скрининг, какого бы он ни был kind, — EXPECTED, ALTERNATIVE и UNEXPECTED одинаково, и независимо от того, разрешили вы его или нет. Деньги, не прошедшие скрининг, не свипаются никогда и до баланса не доходят: они остаются на депозитном адресе.

Свипы повторяются без какого-либо участия с вашей стороны. Свип, который не удалось запустить, запускается снова, пока его не примут, а провалившийся поднимается заново ограниченное число раз, так что временный сбой задерживает деньги, а не оставляет их на адресе. Если свип так и не прошёл, вызовите эндпоинт свипа сами.

Автоматический свип переводит инвойс из PAID в SWAPPING, когда его приняли, и в COMPLETED, когда деньги на вашем балансе. Инвойс, ещё не оплаченный полностью, сохраняет свой статус, пока свипаются его первые платежи, и двигается дальше только после того, как станет PAID. Свип, который сдался, переводит инвойс из SWAPPING в FAILED, пока деньги не унесёт следующий свип; см. жизненный цикл статусов.

Ставьте autoSweep: false, когда хотите сами выбирать момент, — например, чтобы платёж, который вы, возможно, разрешите как REFUNDED, не попадал на баланс, пока вы не решили. Свип — единственный способ увести деньги с депозитного адреса: NullSwap не отправляет возвраты, поэтому при false средства остаются ровно там, где лежат, пока вы их не свипнете.

Перемещение денег стоит сетевой комиссии, и платите её в любом случае вы. В нативной монете сети свип оплачивает свою сетевую комиссию из перемещаемой суммы, поэтому доходит немного меньше, чем было заплачено. Для токена в сети с моделью счетов сетевую комиссию в нативной монете платим мы, а её стоимость в токене по текущему курсу удерживаем из зачисления — вместе со стоимостью approve, которые нужны конвертирующему свипу, и нативной монеты, отправленной на адрес для оплаты перемещения. В UTXO-сетях и в Monero сверх того, что платит сам свип, ничего не удерживается. Из того, что дошло, удерживаются комиссия мерчанта и эта сетевая комиссия, а остальное зачисляется на ваш баланс.

Свип депозитного адреса¶

curl -X POST https://api.pay.nullswap.com/api/v1/wallets/7e2a9c14-8b3d-4c56-a789-0f1e2d3c4b5a/sweep \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
        "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
        "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908"
      }'

walletId в пути — это depositWalletId инвойса или id статического кошелька. Тело необязательно:

Без тела свипаются все токены, у которых на адресе есть чистая сумма. Ответ — 202 со свипом на каждый токен:

{
  "data": [
    {
      "id": "0b1c2d3e-4f50-4617-8a29-3b4c5d6e7f80",
      "walletId": "7e2a9c14-8b3d-4c56-a789-0f1e2d3c4b5a",
      "invoiceId": "b2f4a6c8-0d1e-4f23-9a45-6b7c8d9e0f11",
      "staticWalletId": null,
      "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
      "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
      "trigger": "MANUAL",
      "status": "SWEEPING",
      "amount": "25500000",
      "feeEstimate": null,
      "transferRequestId": "4d5e6f70-8192-4a3b-9c4d-5e6f708192a3",
      "error": null,
      "createdAt": "2026-01-01T12:10:00.000Z",
      "updatedAt": "2026-01-01T12:10:01.000Z",
      "feePercentage": "150",
      "fee": null,
      "feeUsd": null,
      "settledAt": null,
      "creditedTokenId": null,
      "dstTokenId": null,
      "amountIn": null,
      "amountOut": null,
      "conversionSkipReason": null
    }
  ]
}

Правила автоконвертации задаются в кабинете, в разделе Конвертация → Автоконвертация. Свип, подпадающий под такое правило, по пути на ваш баланс конвертируется в целевой токен правила, если это возможно. Если нет, он зачисляется в собственном токене, а conversionSkipReason объясняет почему:

Свип может прийти со статусом FAILED уже в самом ответе 202, если его отклонили в момент запуска. 202 значит, что вызов принят, а не что каждый свип в нём идёт: проверяйте status у каждого.

На один адрес и токен одновременно идёт не больше одного активного (PENDING или SWEEPING) свипа. Если такой уже идёт — автоматический или от вашего предыдущего вызова, — он возвращается как есть, а новый свип запускается только для токенов, у которых его нет. Это не ошибка: trigger: "AUTO" в ответе на ваш вызов значит, что деньги уже были в пути. Поэтому повторять вызов безопасно.

Если на адресе нет ничего чистого сверх пыли, вызов отвечает 422 NOTHING_TO_SWEEP и добавляет объект details с оценкой, чтобы было видно, насколько сумме не хватает:

{
  "statusCode": 422,
  "message": "NOTHING_TO_SWEEP",
  "timestamp": "2026-01-01T12:10:00.000Z",
  "details": {
    "amount": "150000",
    "feeEstimate": "2800000",
    "dust": [
      {
        "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
        "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
        "amount": "150000",
        "feeEstimate": "2800000"
      }
    ]
  }
}

amount — в базовых единицах токена, feeEstimate — в базовых единицах нативной монеты сети; пара верхнего уровня повторяет первый элемент dust. Если чистой суммы нет совсем, dust пуст, amount равен "0", а feeEstimate — null.

В отличие от остального API, адрес другого мерчанта даёт 404, а не 403: ответ не подтверждает, что такой id существует.