Интеграция по API

Принимайте платежи в криптовалюте с внешних криптокошельков через Merchant API.

При интеграции по API ваше приложение создаёт криптоинвойсы, показывает клиентам инструкции по оплате и отслеживает статус платежей через API или уведомления на Status URL.

Использовать API можно тремя способами:

Только API с опросом статуса — ваше приложение строит весь платёжный интерфейс и проверяет статус платежа через API.
Только API с уведомлениями на Status URL — ваше приложение строит весь платёжный интерфейс, а Status URL для уведомлений о платежах берётся из конфигурации Hosted Checkout. Сама страница Hosted Checkout не используется.
API + Hosted Checkout — ваш бэкенд использует API для отслеживания и сверки заказов, а клиент видит страницу оплаты Hosted Checkout.

Когда использовать интеграцию по API

Используйте интеграцию по API, если хотите управлять процессом оплаты на своём сайте, в приложении, боте или ИИ-агенте.

Интеграция по API полезна, если:

Вы хотите сделать собственный интерфейс оплаты.
Вам нужно создавать криптоинвойсы программно.
Вы хотите показывать инструкции по оплате внутри своего продукта.
Вам нужно отслеживать статус платежей на бэкенде.
Вы хотите получать уведомления о статусе платежей на свой сервер.
Вы хотите сочетать Hosted Checkout со сверкой заказов на бэкенде.

Если нужна самая быстрая интеграция с готовой страницей оплаты, используйте интеграцию Hosted Checkout.

Модели интеграции

Модель	Интерфейс для клиента	Задачи бэкенда	Обработка статусов
Только API + опрос	Делает ваше приложение	Создать инвойс, показать реквизиты, отслеживать статус	Опрашивать `GET /api/orders`
Только API + Status URL	Делает ваше приложение	Создать инвойс, показать реквизиты, обрабатывать уведомления	Status URL Hosted Checkout, поиск заказа через API для сверки
API + Hosted Checkout	Размещён на стороне Volet.com	Отслеживать заказы и сверять статус платежей	Status URL Hosted Checkout, поиск заказа через API для сверки

Перед началом

Чтобы принимать криптоплатежи через API, нужны:

Верифицированный аккаунт Volet.com.
Настроенный API в разделе Платёжные инструменты.
Следующие права API:
- Совершать транзакции → Принимать криптоплатежи — для создания криптоинвойсов.
- Поиск транзакции — для получения платёжных заказов.
Конфигурация Hosted Checkout, название которой можно передавать в sciName.

Как создать и настроить API и Hosted Checkout, описано в разделе Создание платёжного шлюза.

Текущее требование к sciName

В текущей реализации GET /api/orders для получения заказа требуется название Hosted Checkout (sciName).

Пока это требование не снято, создайте конфигурацию Hosted Checkout и передавайте её название в sciName при создании криптоинвойсов, которые нужно отслеживать.

Перенаправлять клиентов на страницу Hosted Checkout не нужно. Конфигурацию можно использовать только для того, чтобы получить нужный sciName и, при желании, уведомления на Status URL.

Аутентификация

Запросы к Merchant API требуют заголовков аутентификации.

Передавайте в каждом запросе к API следующие заголовки:

Заголовок	Описание
`Api-Name`	Название API, заданное в аккаунте Volet.com.
`Account-Email`	Email аккаунта Volet.com, которому принадлежит API.
`Authentication-Token`	Токен SHA-256, сгенерированный из `password:YYYYMMDD:HH` (UTC), где пароль задаётся в вашем аккаунте Volet.com в разделе «Платёжные инструменты».

Например:

SHA256("MySecret123:20261026:14")

даёт:

c98e6521afe72b0945d9fdefdf3fd0b4dea10baa7f69325a7d6381c15f2421fd

Значение токена меняется каждый час по UTC. Генерируйте новый токен непосредственно перед каждым запросом, чтобы не отправить токен, созданный в предыдущий час.

В API передаётся только сгенерированный токен. Никогда не отправляйте пароль API.

Храните пароль API в тайне. Никогда не размещайте учётные данные API и токены аутентификации во фронтенд-коде, мобильных приложениях, ботах или клиентских скриптах.

Пример запроса с аутентификацией:

curl -X POST https://api.volet.com/api/invoice/crypto-invoice/deposit \
  -H "Content-Type: application/json" \
  -H "Api-Name: my-store-api" \
  -H "Account-Email: [email protected]" \
  -H "Authentication-Token: c98e6521afe72b0945d9fdefdf3fd0b4dea10baa7f69325a7d6381c15f2421fd" \
  -d '{
    "receiverCurrency": "USD",
    "senderCurrency": "USDT_TRC20",
    "amount": 100,
    "transferAction": "GET",
    "sciName": "Store",
    "orderId": "ORDER-1001"
  }'

Сценарий оплаты «только API»

Используйте этот сценарий, если ваше приложение полностью отвечает за процесс криптоплатежа.

Создайте заказ в своей системе.
При необходимости проверьте расчётные параметры инвойса.
Создайте криптоинвойс через API.
Покажите клиенту адрес для оплаты, сумму, валюту, сеть и срок действия.
Клиент отправляет платёж с криптокошелька.
Отслеживайте платёж через GET /api/orders, уведомления на Status URL или оба способа сразу.
Когда платёж завершён, обновите статус заказа в своей системе.

Шаг 1 (необязательный). Проверьте параметры инвойса

Перед созданием инвойса можно проверить его расчётные значения.

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

Эндпоинт:

POST /api/invoice/crypto-invoice/check

См. Проверка криптоинвойса в справочнике API.

Пример запроса:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com"
}

Пример ответа:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com",
  "senderAmount": 100,
  "receiverAmount": 100,
  "expirationDate": "2026-01-15T10:30:00",
  "expirationDateMillis": 1768473000000
}

Этот шаг не создаёт адрес для оплаты и не запускает платёж.

Шаг 2. Создайте криптоинвойс

Создавайте криптоинвойс, когда клиент готов платить.

Эндпоинт:

POST /api/invoice/crypto-invoice/deposit

См. Создание криптоинвойса на пополнение в справочнике API.

Пример запроса:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com"
}

В ответе возвращаются реквизиты, которые ваше приложение должно показать клиенту.

Пример ответа:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com",
  "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "addressOldFormat": null,
  "destinationTag": null,
  "senderAmount": 100,
  "receiverAmount": 100,
  "expirationDate": "2026-01-15T10:30:00",
  "expirationDateMillis": 1768473000000
}

Суммы в этих примерах условные. Фактические senderAmount и receiverAmount зависят от выбранных валют, курса обмена и действующих комиссий.

Поля запроса инвойса

Поле	Обязательное	Описание
`receiverCurrency`	Да	Валюта, которая зачисляется на ваш аккаунт Volet.com после завершения платежа. Поддерживаемые значения см. в справочнике API.
`senderCurrency`	Да	Валюта и сеть, в которых клиент должен заплатить, например `USDT_TRC20`.
`amount`	Да	Сумма платежа. Как она интерпретируется, зависит от `transferAction`.
`transferAction`	Да	Определяет, к какой стороне относится `amount`. Возможные значения: `GIVE`, `GET`. См. `GIVE` и `GET`.
`note`	Нет	Примечание к платежу или описание заказа. До 255 символов.
`sciName`	Нет*	Название Hosted Checkout, заданное в аккаунте Volet.com. Сейчас обязательно, если вы хотите получать заказ через `GET /api/orders` или получать уведомления на Status URL через конфигурацию Hosted Checkout.
`orderId`	Нет*	Ваш внутренний ID заказа, до 64 символов. Нужен, чтобы позже получить платёж через `GET /api/orders`. Используйте уникальное значение для каждого платежа.
`subMerchantURL`	Нет	URL сайта субмерчанта, если платёж обрабатывается от имени другого мерчанта. См. Субмерчанты.

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

`GIVE` и `GET`

transferAction определяет, в какой валюте выражена сумма amount в запросе.

Значение	Что означает `amount`
`GIVE`	Сумму, которую отправляет клиент, в валюте `senderCurrency`.
`GET`	Сумму, которая будет зачислена на ваш аккаунт Volet.com, в валюте `receiverCurrency`.

Итоговые senderAmount и receiverAmount, которые возвращает API, могут отличаться из-за курса обмена и действующих комиссий.

Коды валют

Коды некоторых криптовалют содержат блокчейн-сеть после символа подчёркивания.

Например:

USDT_TRC20 — USDT в сети Tron.
USDT_ERC20 — USDT в сети Ethereum.
USDC_SOL — USDC в сети Solana.

Для остальных активов используется один код валюты, например BTC, ETH или TON.

Допустимые значения см. в разделе Поддерживаемые валюты и токены и в справочнике API.

Поля ответа инвойса

Поле	Описание
`address`	Криптоадрес, на который клиент должен отправить платёж.
`addressOldFormat`	Альтернативный формат адреса, если он есть для выбранной сети.
`destinationTag`	Destination tag, memo или другой идентификатор, который нужен в некоторых сетях.
`senderAmount`	Сумма, которую должен отправить клиент.
`senderCurrency`	Валюта и сеть, которые должен использовать клиент.
`receiverAmount`	Сумма, которая ожидается к зачислению на ваш аккаунт.
`receiverCurrency`	Валюта, которая ожидается к зачислению на ваш аккаунт.
`expirationDate`	Дата и время истечения срока инвойса.
`expirationDateMillis`	Время истечения срока инвойса в виде Unix-времени в миллисекундах.

Всегда показывайте точные senderAmount, senderCurrency, address и destinationTag, если он вернулся в ответе.

Рассчитывайте и показывайте время истечения срока инвойса по expirationDateMillis.

Шаг 3. Покажите инструкции по оплате

В режиме «только API» показывать клиенту инструкции по оплате должно ваше приложение.

Покажите как минимум:

Сумму к отправке.
Валюту и блокчейн-сеть.
Криптоадрес.
Destination tag или memo, если они нужны.
Срок действия.
Предупреждение, что средства нужно отправлять только в выбранной сети.

Пример:

Send exactly 100 USDT on Tron (TRC-20) to:

TXXXXXXXXXXXXXXXXXXXXXXXXXXXX

This invoice expires at 2026-01-15 10:30 UTC.

Do not send funds on another network.

Для сетей, где нужен destination tag или memo, показывайте его на видном месте рядом с адресом.

Шаг 4. Проверьте статус платежа

После создания инвойса бэкенд может получить платёжный заказ через API.

Эндпоинт:

GET /api/orders

См. Получение платёжного заказа в справочнике API.

Текущие параметры запроса:

Параметр	Обязательный	Описание
`orderId`	Да	Идентификатор заказа мерчанта, до 64 символов.
`sciName`	Да*	Название Hosted Checkout, связанное с инвойсом.

* Сейчас реализация API требует sciName при получении заказа.

Пример запроса:

GET /api/orders?orderId=ORDER-1001&sciName=Store

Временное решение для sciName

Сейчас заказ, созданный через API, нельзя надёжно получить только по orderId.

Создайте конфигурацию Hosted Checkout, укажите её название в sciName при создании криптоинвойса и передайте то же значение в GET /api/orders.

Это решение работает и без показа клиенту страницы Hosted Checkout.

Пример ответа:

{
  "orderId": "ORDER-1001",
  "sciName": "Store",
  "paymentStatus": "PENDING",
  "paymentMethod": "CRYPTO_INVOICE",
  "paymentCreated": "2026-01-15T10:00:00",
  "transaction": {
    "id": "11111111-1111-4111-8111-111111111111",
    "status": "PENDING",
    "senderAmount": 100,
    "senderCurrency": "USDT_TRC20",
    "receiverAmount": 100,
    "receiverCurrency": "USD",
    "created": "2026-01-15T10:00:00"
  },
  "invoice": {
    "created": "2026-01-15T10:00:00",
    "received": "2026-01-15T10:12:00",
    "invoiceStatus": "RECEIVED",
    "externalStatus": "PAYMENT_RECEIVED",
    "penalties": [],
    "cryptoCurrencyAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "initialSenderAmount": 100,
    "actualReceivedAmount": 100,
    "senderCurrency": "USDT_TRC20",
    "cryptoCurrencyTransactionId": "11111111-1111-4111-8111-111111111111"
  }
}

Если подходящий заказ не найден, API может вернуть 404. Прежде чем создавать для того же заказа новый инвойс, проверьте orderId и sciName.

Статус платежа

Определяйте, завершён ли платёж, по paymentStatus верхнего уровня.

Статус	Значение	Что делать
`PENDING`	Платёж ещё не перешёл в итоговое завершённое состояние.	Оставьте заказ в ожидании.
`COMPLETED`	Платёж успешно завершён.	Отметьте заказ как оплаченный и передайте товар или услугу.
`CANCELED`	Платёж отменён.	Не выполняйте заказ.
`REFUNDED`	Платёж возвращён.	Обновите заказ согласно вашему процессу возвратов.

Считайте заказ оплаченным, только когда paymentStatus равен COMPLETED.

В ответе также есть поля инвойса, например invoiceStatus, externalStatus и penalties. Они могут содержать дополнительные сведения о криптоинвойсе.

Не выводите итоговый статус заказа из недокументированных значений externalStatus или penalties. Используйте их, только если ваша интеграция явно обрабатывает значения, которые возвращает API.

cryptoCurrencyTransactionId — идентификатор криптотранзакции, который возвращает API. Не считайте, что это хеш транзакции в блокчейне, пока это не подтверждено для выбранного платёжного сценария.

Получение уведомлений на Status URL

Опрос GET /api/orders — не единственный способ отслеживать криптоинвойсы, созданные через API.

В настройках API в аккаунте Volet.com сейчас нет полей для URL вебхуков. Однако для получения уведомлений о статусе платежей по инвойсам, созданным через API, можно использовать Status URL, настроенный для шлюза Hosted Checkout.

В этом сценарии не нужно показывать клиентам Hosted Checkout или перенаправлять их туда.

Настройка уведомлений на Status URL

Создайте конфигурацию Hosted Checkout в аккаунте Volet.com.
Укажите в ней Status URL и выберите нужный HTTP-метод.
Передавайте название Hosted Checkout в sciName при создании криптоинвойсов через API.
Оставьте процесс оплаты для клиента в своём приложении.
Когда статус платежа меняется, Volet.com отправляет уведомление на Status URL, настроенный для этого Hosted Checkout.
Проверьте подпись уведомления, прежде чем обновлять заказ в своей системе.
При необходимости используйте GET /api/orders для сверки или как резервную проверку.

Пример запроса на создание инвойса:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001"
}

В этом примере Store — название конфигурации Hosted Checkout, в которой задан Status URL.

Клиент по-прежнему видит ваш собственный платёжный интерфейс. Страница оплаты Hosted Checkout не открывается.

примечание

Таким образом, в интеграции «только API» один и тот же sciName решает две задачи:

Позволяет текущей реализации GET /api/orders найти заказ.
Связывает созданный через API инвойс с конфигурацией Hosted Checkout, через которую приходят уведомления на Status URL.

Параметры уведомлений и проверка подписи описаны в разделе Интеграция Hosted Checkout.

Опрос и уведомления на Status URL

Можно использовать:

Опрос через API.
Уведомления на Status URL.
Оба способа вместе.

Если интеграция использует уведомления на Status URL, поиск заказа через API помогает при сверке, когда уведомление задерживается или ваш эндпоинт временно недоступен.

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

Сценарий «API + Hosted Checkout»

Используйте эту модель, если страницу оплаты для клиента должен показывать сам Hosted Checkout, а ваш бэкенд использует API для отслеживания и сверки.

Порядок платежа:

Создайте заказ в своей системе.
Перенаправьте клиента на Hosted Checkout через вашу интеграцию Hosted Checkout.
Передайте свой orderId в платёжном запросе Hosted Checkout.
Клиент завершает платёж на странице Hosted Checkout.
Volet.com отправляет уведомление о статусе платежа на ваш Status URL.
Бэкенд проверяет подпись уведомления.
Бэкенд обновляет статус заказа.
При необходимости бэкенд проверяет заказ через API для сверки.

В этой модели Hosted Checkout отвечает за:

Страницу оплаты.
Выбор платёжного метода.
Инструкции по оплате.
Перенаправление клиента.

API по-прежнему можно использовать, чтобы получить платёжный заказ по orderId и sciName и сверить статус в своей системе.

Обработка статусов с Hosted Checkout

Если вы используете страницу Hosted Checkout, не полагайтесь только на перенаправления на Success URL или Failed URL.

Перенаправления клиента происходят в браузере и не всегда доходят до вашего сервера.

Обновляйте заказ на бэкенде по уведомлению на Status URL, а при необходимости сверяйте его через поиск заказа в API.

Рекомендуемый порядок:

Получите уведомление Hosted Checkout на Status URL.
Проверьте подпись уведомления.
Если уведомление корректно, обновите заказ.
Используйте GET /api/orders как резервную проверку или для сверки.

Формат уведомления и правила проверки подписи описаны в разделе Интеграция Hosted Checkout.

Обработка ошибок

При ошибках Merchant API возвращает структурированный ответ с одной или несколькими ошибками в data.errors.

Пример структуры:

{
  "status": "error",
  "data": {
    "errors": [
      {
        "errorMessage": "resourceNotFound",
        "errorType": "GENERAL",
        "errorId": "3f69d9b6",
        "errorDescription": "Resource not found",
        "errorField": null,
        "params": [],
        "requestParams": {}
      }
    ]
  }
}

Поля ошибки:

Поле	Описание
`errorMessage`	Машиночитаемый код ошибки, который возвращает API.
`errorType`	Категория ошибки.
`errorId`	Идентификатор ошибки, который можно указывать в логах и обращениях в поддержку.
`errorDescription`	Описание ошибки для человека.
`errorField`	Поле запроса, к которому относится ошибка, если оно известно.
`params`	Дополнительные параметры ошибки, если они есть.
`requestParams`	Параметры запроса, связанные с ошибкой, если они есть.

Частые HTTP-ответы:

HTTP-статус	Значение
`400`	Запрос сформирован неверно или содержит недопустимые параметры.
`401`	Заголовки аутентификации отсутствуют или недействительны.
`404`	Запрошенный ресурс не найден.
`500`	Непредвиденная ошибка сервера.

Конкретные значения errorMessage зависят от эндпоинта и ошибки. Не определяйте код ошибки приложения только по HTTP-статусу.

Когда возникает ошибка:

Записывайте errorId в лог для поддержки и диагностики.
Смотрите errorField, если он есть.
В программной обработке ошибок опирайтесь на errorMessage, а не на errorDescription.
Не создавайте автоматически дубликат инвойса после запроса, результат которого неясен.
Повторяйте запрос, только если это безопасно.

Тестирование и песочница

Сейчас Volet.com не предоставляет песочницу или тестовую среду для проверки интеграции.

Если вы используете Hosted Checkout, страницу оплаты для клиента можно посмотреть на странице Hosted Checkout для разработчиков. Это предпросмотр, а не песочница, и он не заменяет тестирование интеграции.

Чтобы разобрать API, Hosted Checkout и процесс оплаты до запуска, свяжитесь с отделом продаж Volet.com.

Чек-лист тестирования

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

Для интеграций «только API»:

Проверка инвойса, если используется.
Создание инвойса.
Правильное отображение адреса для оплаты.
Отображение destination tag или memo, где они нужны.
Правильное отображение валюты и сети.
Обработка истечения срока инвойса.
Сохранение orderId и sciName.
Поиск заказа через GET /api/orders.
Обработка завершённого платежа.
Обработка отменённых платежей и возвратов.
Обработка повторного orderId.
Обработка ошибок API.

Если вы используете уведомления на Status URL:

В конфигурации Hosted Checkout указан правильный Status URL.
В sciName передаётся то же название Hosted Checkout.
Уведомления доходят до вашего бэкенда.
Подписи уведомлений проверяются.
Повторные уведомления обрабатываются безопасно.
Для сверки можно использовать поиск заказа через API.

Если вы используете страницу оплаты Hosted Checkout, проверьте также:

Перенаправление клиента на Hosted Checkout.
Перенаправление на Success URL.
Перенаправление на Failed URL.
Доставку уведомлений на Status URL.
Проверку подписи уведомлений.
Поиск заказа через API для сверки.

Важно

В интеграциях «только API» клиентам не нужно заходить на Hosted Checkout.
Текущий поиск заказа требует sciName.
Конфигурацию Hosted Checkout можно использовать только для sciName и уведомлений на Status URL, не показывая страницу Hosted Checkout.
Всегда используйте уникальный orderId для каждого платежа.
Всегда показывайте точные адрес, сумму, валюту, сеть и destination tag, которые вернул API.
Не отмечайте заказ как оплаченный, пока paymentStatus не станет COMPLETED.
Рассчитывайте истечение срока инвойса по expirationDateMillis.
Криптоплатежи зависят от подтверждений в блокчейне и состояния сети.
Отправка средств на неверный адрес или в неверной сети может привести к их безвозвратной потере.
Не создавайте автоматически новый инвойс после таймаута с неясным результатом или временной ошибки API.

Создание платёжного шлюза — создание и настройка API и Hosted Checkout
Приём кастодиальных криптоплатежей — как работают кастодиальные криптоплатежи
Интеграция Hosted Checkout — готовая страница оплаты и уведомления на Status URL
Поддерживаемые валюты и токены — поддерживаемые валюты и сети
Справочник API — полное описание методов, параметров и ответов

Когда использовать интеграцию по API​

Модели интеграции​

Перед началом​

Аутентификация​

Сценарий оплаты «только API»​

Шаг 1 (необязательный). Проверьте параметры инвойса​

Шаг 2. Создайте криптоинвойс​

Поля запроса инвойса​

GIVE и GET​

Коды валют​

Поля ответа инвойса​

Шаг 3. Покажите инструкции по оплате​

Шаг 4. Проверьте статус платежа​

Статус платежа​

Получение уведомлений на Status URL​

Настройка уведомлений на Status URL​

Опрос и уведомления на Status URL​

Сценарий «API + Hosted Checkout»​

Обработка статусов с Hosted Checkout​

Обработка ошибок​

Тестирование и песочница​

Чек-лист тестирования​

Важно​

См. также​

Когда использовать интеграцию по API

Модели интеграции

Перед началом

Аутентификация

Сценарий оплаты «только API»

Шаг 1 (необязательный). Проверьте параметры инвойса

Шаг 2. Создайте криптоинвойс

Поля запроса инвойса

`GIVE` и `GET`

Коды валют

Поля ответа инвойса

Шаг 3. Покажите инструкции по оплате

Шаг 4. Проверьте статус платежа

Статус платежа

Получение уведомлений на Status URL

Настройка уведомлений на Status URL

Опрос и уведомления на Status URL

Сценарий «API + Hosted Checkout»

Обработка статусов с Hosted Checkout

Обработка ошибок

Тестирование и песочница

Чек-лист тестирования

Важно

См. также