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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Верифицированный аккаунт Volet.com.
• Настроенный API в разделе Платёжные инструменты.
• Права API на приём криптоплатежей.
• Конфигурация Hosted Checkout, если вы используете API вместе с Hosted Checkout.

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

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

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

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

Заголовок	Описание
Api-Name	Название API, заданное в аккаунте Volet.com.
Account-Email	Email аккаунта Volet.com, которому принадлежит API.
Authentication-Token	Токен аутентификации запроса, сгенерированный с помощью секрета API.

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

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

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

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

1. Создайте заказ в своей системе.
2. При необходимости проверьте параметры инвойса до его создания.
3. Создайте криптоинвойс через API.
4. Покажите клиенту адрес для оплаты, сумму, валюту, сеть и срок действия.
5. Клиент отправляет платёж с криптокошелька.
6. Ваш бэкенд проверяет статус платежа через API.
7. Когда платёж завершён, обновите статус заказа в своей системе.

Шаг 1. Проверьте параметры инвойса

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

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

Эндпоинт:

POST /api/invoice/crypto-invoice/check

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

{
  "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

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

{
  "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
}

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

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

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

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

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

Шаг 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. Проверьте статус платежа

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

Эндпоинт:

GET /api/orders

Обязательный параметр запроса:

Параметр	Описание
orderId	Идентификатор заказа мерчанта.

Необязательный параметр запроса:

Параметр	Описание
sciName	Название Hosted Checkout или магазина, связанное с заказом.

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

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

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

{
  "orderId": "ORDER-1001",
  "sciName": "Store",
  "paymentStatus": "PROCESSING",
  "paymentMethod": "CRYPTO_INVOICE",
  "paymentCreated": "2026-01-15T10:30:00",
  "transaction": {
    "status": "PROCESSING"
  },
  "invoice": {
    "invoiceStatus": "PROCESSING",
    "cryptoCurrencyAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "initialSenderAmount": 100,
    "actualReceivedAmount": 100,
    "senderCurrency": "USDT_TRC20",
    "cryptoCurrencyTransactionId": "11111111-1111-4111-8111-111111111111"
  }
}

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

По paymentStatus определяйте, как обновить заказ в своей системе.

Статус	Значение	Что делать
CREATED	Инвойс создан и ожидает оплаты.	Оставьте заказ в ожидании.
PROCESSING	Платёж обнаружен или обрабатывается.	Оставьте заказ в ожидании и продолжайте проверять статус.
COMPLETED	Платёж успешно завершён.	Отметьте заказ как оплаченный и передайте товар или услугу.
FAILED	Платёж не прошёл, истёк или не может быть завершён.	Не выполняйте заказ. Попросите клиента создать новый платёж.

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

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

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

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

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

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

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

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

При использовании Hosted Checkout не полагайтесь только на перенаправления на Success URL или Failed URL.

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

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

1. Получите уведомление Hosted Checkout на Status URL.
2. Проверьте подпись уведомления.
3. Если уведомление корректно, обновите статус заказа.
4. Используйте поиск заказа через API как резервную проверку или для сверки.

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

При ошибках Merchant API возвращает структурированный ответ с ошибкой.

Частые случаи:

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

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

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

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

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

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

• Проверку инвойса.
• Создание инвойса.
• Отображение адреса для оплаты.
• Отображение destination tag или memo, где они нужны.
• Обработку истечения срока инвойса.
• Периодический запрос статуса заказа.
• Обработку завершённого платежа.
• Обработку неудачного или просроченного платежа.
• Обработку повторного orderId.

Для интеграций «API + Hosted Checkout» также проверьте:

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

Важно

• Интеграции «только API» не используют колбэки Hosted Checkout.
• Бэкенд должен проверять статус платежа через API.
• Всегда используйте уникальный orderId для каждого платежа.
• Всегда показывайте точные адрес, сумму, валюту, сеть и destination tag, которые вернул API.
• Не отмечайте заказ как оплаченный, пока статус платежа не станет COMPLETED.
• Криптоплатежи зависят от подтверждений в блокчейне и состояния сети.
• Отправка средств на неверный адрес или в неверной сети может привести к их безвозвратной потере.

См. также

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