Документация для мерчантов NullSwap¶

NullSwap позволяет вашему бэкенду принимать криптоплатежи. Вы запрашиваете адрес для пополнения, показываете его клиенту, а когда деньги дойдут и пройдут скрининг, мы присылаем вебхук.

Весь этот сайт описывает API мерчанта — серверный HTTP-API, где аутентификация сводится к одному API-ключу. Ни браузерных редиректов, ни OAuth, ни сессий здесь нет.

https://api.pay.nullswap.com

У этого же API есть интерактивный справочник Swagger по адресу api.pay.nullswap.com/docs, собранный из самого API. Там удобно свериться с точным именем поля или отправить пробный запрос; понять сами сценарии помогает этот сайт. См. Вне префикса версии.

Два способа принимать деньги¶

В API есть две модели приёма средств. Они независимы — используйте одну или обе сразу.

Начните с инвойсов. Статические кошельки пригодятся тогда, когда адрес нужен под клиента, а не под заказ.

Полный путь инвойса¶

sequenceDiagram
    autonumber
    participant B as Ваш бэкенд
    participant N as NullSwap
    participant C as Клиент
    participant W as Ваш эндпоинт вебхука

    B->>N: POST /api/v1/invoices (chain, token, expectedAmount)
    N-->>B: 201 { id, depositAddress, expiresAt, status: WAITING }
    B->>C: показать depositAddress и точную сумму, до expiresAt
    C->>N: отправляет токены в сети

    N->>W: invoice.payment_detected · статус PAYMENT_DETECTED
    Note over W: не подтверждён — покажите прогресс, ничего не отгружайте

    N->>N: достигнута глубина подтверждений, выполняется AML-скрининг
    N->>W: invoice.payment_confirmed · платёж CONFIRMED
    N->>W: invoice.paid · статус PAID, paidAmount >= expectedAmount
    Note over W: это сигнал к исполнению заказа

    W-->>N: 2xx

Шаги 5, 7 и 8 — это доставки вебхуков. Запрос GET /api/v1/invoices/{invoiceId} вернёт ровно то же состояние, но опрос — это способ восстановиться после простоя вашего эндпоинта, а не способ интеграции.

После invoice.paid деньги всё ещё лежат на депозитном адресе. Они свипаются на ваш баланс — автоматически или по вашему запросу, если инвойс создан с autoSweep: false, — и выводите вы их уже оттуда. См. перевод средств на баланс. Свип зачисляется за вычетом комиссии мерчанта, а для токена — ещё и сетевой комиссии за его перемещение. Свип к тому же переводит инвойс в SWAPPING, а затем в COMPLETED с событиями invoice.swapping и invoice.completed.

С чего начать¶

1. Получите API-ключ. В кабинете владелец мерчанта нажимает Выпустить ключ в разделе Настройки → API-ключ и сразу копирует ключ: он показывается только один раз. Ключ начинается с sk_live_. Ключи, белые списки IP и подписки на вебхуки заводятся вручную в кабинете — через API их не создать и не изменить. См. Аутентификацию.
2. Определите сеть и токен. GET /api/v1/chains и GET /api/v1/tokens вернут UUID, по которым потом адресуется инвойс. Закешируйте их. См. Сети и токены.
3. Создайте инвойс. POST /api/v1/invoices. В ответе придёт depositAddress — покажите его клиенту или отрисуйте QR-код. На RIPPLE покажите вместе с ним обязательный depositTag. См. Инвойсы.
4. Обработайте вебхук. Проверьте HMAC-подпись, отбросьте повторы по id доставки, быстро ответьте 2xx и исполняйте заказ по invoice.paid. См. Вебхуки.

Частые ошибки¶

Суммы приходят строками, а не JSON-числами. Каждая сумма — это десятичная строка с целым числом базовых единиц токена, а рядом лежит decimals этого токена. 25.50 USDT в TRON записывается как "25500000" при decimals: 6. См. Суммы.

Ошибку определяет её код, а не текст. В поле message приходит стабильный машиночитаемый код — разбирайте именно его, а не HTTP-статус сам по себе и не формулировку.

{
  "statusCode": 422,
  "message": "INVALID_INVOICE_AMOUNT",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

Полный список см. в Ошибках.

Что читать дальше¶