Инвойсы¶

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

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

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",
  "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
  "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
  "expectedAmount": "25500000",
  "acceptsAnyToken": false,
  "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 уберите их с экрана.

Ошибки¶

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

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

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

GET /api/v1/invoices/stats принимает chainId, tokenId, createdFrom и createdTo и возвращает количества, сгруппированные тремя способами:

{
  "total": 137,
  "byStatus": [{ "status": "PAID", "count": 96 }],
  "byToken": [{
    "chainId": "1c9a7f36-...",
    "tokenId": "3b7e1a48-...",
    "count": 96,
    "expectedAmount": "2448000000",
    "paidAmount": "2451300000"
  }],
  "byDay": [{ "date": "2026-01-01", "count": 12, "paidCount": 9 }]
}

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

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 --> SWAPPING
    SWAPPING --> COMPLETED
    SWAPPING --> FAILED

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

Три вещи, которые на диаграмме есть, но легко ускользают от внимания:

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

COMPLETED, FAILED и 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. Деньги записываются и там, и там; флаг меняет только их классификацию и то, спросят ли у вас решение по ним. См. Платежи по инвойсу.