Перейти к основному содержимому

Интеграция Hosted Checkout

Hosted Checkout — готовая страница оплаты, размещённая на стороне Volet.com.

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

Ваше приложение создаёт платёжный запрос и перенаправляет клиента на Hosted Checkout. Клиент завершает платёж, Volet.com отправляет уведомление о статусе на ваш сервер и затем перенаправляет клиента обратно на ваш сайт.

Hosted Checkout поддерживает:

Перед интеграцией создайте и настройте шлюз Hosted Checkout в своём аккаунте. См. Создание платёжного шлюза.

Порядок оплаты​

  1. Клиент оформляет заказ на вашем сайте.
  2. Ваш сайт формирует платёжный запрос и показывает кнопку или ссылку для оплаты.
  3. Клиент нажимает Оплатить и попадает на Hosted Checkout.
  4. Клиент завершает платёж.
  5. Volet.com отправляет уведомление о статусе платежа на ваш Status URL.
  6. Ваша система обновляет статус заказа.
  7. Hosted Checkout показывает страницу с результатом платежа.
  8. Клиент может нажать Продолжить и перейти на ваш Success URL или Failed URL.
Merchant website
│
▼
Hosted Checkout
│
▼
Payment
│
▼
Status URL
│
▼
Merchant backend
│
▼
Customer redirect

Для успешных платежей страница результата содержит ID транзакции и информацию о платеже. Для неудачных или отменённых — соответствующее сообщение об ошибке или отмене.

Success URL и Failed URL можно задать в настройках Hosted Checkout или передать динамически в платёжном запросе.

примечание

Обновляя статус заказа, всегда опирайтесь на уведомления на Status URL. Не полагайтесь только на перенаправления в браузере.

Success URL и Failed URL не должны использоваться для определения итогового статуса платежа.

Быстрый старт Hosted Checkout​

Шаг 1. Создайте платёжный запрос​

Эндпоинт Hosted Checkout​

https://account.volet.com/api/public/payment-gateway

Обязательные параметры​

Чтобы создать платёж, отправьте HTML-форму методом POST на указанный выше эндпоинт. Платёжный запрос должен содержать следующие обязательные параметры:

ПараметрОписание
ac_account_emailEmail вашего аккаунта Volet.com
ac_sci_nameНазвание Hosted Checkout
ac_amountСумма платежа
ac_currencyВалюта платежа (например, USD, EUR)
ac_order_idВаш уникальный идентификатор заказа
ac_signЦифровая подпись

Полный список поддерживаемых параметров — в разделе Параметры платёжного запроса.

примечание

Каждый платёжный запрос должен использовать уникальный ac_order_id.

Не используйте один и тот же идентификатор заказа для разных платежей.

Подпись запроса​

Параметр ac_sign формируется как SHA-256-хеш следующей строки:

ac_account_email:ac_sci_name:ac_amount:ac_currency:secret:ac_order_id

где secret — пароль, который вы задали при создании Hosted Checkout.

Пример строки:

[email protected]:Store:100.00:USD:password:123

SHA-256-хеш:

eb9e7f491df701fe7d71c74551ae9e4226dfbed7e3a9cc4916e242d3c09f718e

Передайте полученный хеш в параметре ac_sign.

Отправка платёжного запроса​

Отправьте HTML-форму на эндпоинт Hosted Checkout методом POST.

Пример платёжного запроса​

<form method="POST" action="https://account.volet.com/api/public/payment-gateway">
<input type="hidden" name="ac_account_email" value="[email protected]">
<input type="hidden" name="ac_sci_name" value="Store">
<input type="hidden" name="ac_amount" value="100.00">
<input type="hidden" name="ac_currency" value="USD">
<input type="hidden" name="ac_order_id" value="123">
<input type="hidden" name="ac_sign" value="eb9e7f491df701fe7d71c74551ae9e4226dfbed7e3a9cc4916e242d3c09f718e">
<button type="submit">VoletPay</button>
</form>

Шаг 2. Обрабатывайте уведомления о платежах​

Когда статус платежа меняется, Volet.com отправляет уведомление на ваш Status URL.

Уведомление отправляется методом GET или POST в зависимости от настроек Hosted Checkout.

Уведомление содержит следующие параметры:

ПараметрОписание
ac_transferID транзакции Volet.com
ac_transaction_statusСтатус платежа
ac_order_idВаш идентификатор заказа
ac_amountИсходная сумма платежа
ac_merchant_amountСумма, зачисленная на ваш аккаунт
ac_merchant_currencyВалюта расчёта
ac_start_dateДата и время транзакции
ac_sci_nameНазвание Hosted Checkout
ac_src_walletКошелёк клиента
ac_dest_walletКошелёк мерчанта
ac_buyer_emailEmail клиента (если доступен)
ac_hashХеш подписи уведомления

Полный список доступных параметров — в разделе Параметры уведомления о платеже.

Прежде чем обновлять статус заказа, проверьте подпись ac_hash, чтобы убедиться, что уведомление отправлено Volet.com.

предупреждение

Не отмечайте заказ как оплаченный по перенаправлению клиента.

Всегда дожидайтесь корректного уведомления на Status URL и проверяйте подпись ac_hash, прежде чем обновлять статус заказа.

Пример уведомления, отправленного на Status URL:

<form method="POST" action="https://merchant.example.com/status">
<input type="hidden" name="ac_transfer" value="235f9d0b-b48f-462c-9949-621c4930490c">
<input type="hidden" name="ac_transaction_status" value="COMPLETED">
<input type="hidden" name="ac_order_id" value="123">
<input type="hidden" name="ac_amount" value="100.00">
<input type="hidden" name="ac_merchant_amount" value="100.00">
<input type="hidden" name="ac_merchant_currency" value="USD">
<input type="hidden" name="ac_start_date" value="2026-06-23 12:30:00">
<input type="hidden" name="ac_sci_name" value="Store">
<input type="hidden" name="ac_src_wallet" value="USD123456789012">
<input type="hidden" name="ac_dest_wallet" value="USD210987654321">
<input type="hidden" name="ac_buyer_email" value="[email protected]">
<input type="hidden" name="ac_hash" value="4ceab247ca917e0142b1a99015beaed9310cd6a85ab3bacf08ba44d5ac03590b">
</form>

Проверка подписи уведомления​

Чтобы проверить уведомление, вычислите SHA-256-хеш по значениям ниже и сравните его с полученным ac_hash.

Строка для подписи собирается в таком порядке:

ac_transfer:ac_start_date:ac_sci_name:ac_src_wallet:ac_dest_wallet:ac_order_id:ac_amount:ac_merchant_currency:password

где password — пароль Hosted Checkout, заданный для шлюза.

Пример строки:

235f9d0b-b48f-462c-9949-621c4930490c:2026-06-23 12:30:00:Store:USD123456789012:USD210987654321:123:100.00:USD:password

Вычислите SHA-256-хеш этой строки:

4ceab247ca917e0142b1a99015beaed9310cd6a85ab3bacf08ba44d5ac03590b

Сравните вычисленный хеш с полученным ac_hash. Перед обновлением статуса заказа значения должны совпасть.

После успешной проверки подписи обновите соответствующий заказ в своей системе по полученному статусу платежа.

Шаг 3. Проверьте интеграцию​

Прежде чем принимать реальные платежи, проверьте:

  • Перенаправление клиента на Hosted Checkout.
  • Успешное завершение платежа.
  • Доставку уведомлений на Status URL.
  • Проверку подписи уведомлений.
  • Обновление статуса заказов.
  • Перенаправления на Success URL и Failed URL.
  • Обработку неудачных платежей.

IP-адреса серверов уведомлений​

Если в вашей инфраструктуре используются белые списки IP или правила файрвола, разрешите входящие запросы со следующих серверов уведомлений Volet.com:

  • 13.61.247.159

Расширенная настройка​

В разделах ниже описаны необязательные функции и расширенные сценарии интеграции.

Предварительный выбор платёжного метода​

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

Платёжный метод можно выбрать заранее с помощью параметра ac_ps в платёжном запросе. Если он указан, Hosted Checkout сразу открывает экран оплаты выбранным методом и пропускает шаг выбора.

Добавьте в параметры платёжного запроса следующие поля:

  1. Сразу открывает страницу входа в аккаунт Volet.com:
<input type="hidden" name="ac_ps" value="VOLET">
  1. Сразу открывает страницу оплаты в USDT в сети Tron:
<input type="hidden" name="ac_ps" value="USDTETHER">
<input type="hidden" name="ac_ps_protocol" value="TRON">
  1. Сразу открывает страницу оплаты в Bitcoin:
<input type="hidden" name="ac_ps" value="BITCOIN">

Это удобно, если клиент уже выбрал платёжный метод на вашем сайте до перехода на Hosted Checkout.

Язык​

Параметр ac_client_lang задаёт язык интерфейса Hosted Checkout.

Пример:

<input type="hidden" name="ac_client_lang" value="en">

Если язык не указан, Hosted Checkout использует язык по умолчанию, доступный клиенту.

Собственные поля​

В платёжный запрос можно добавить до 10 собственных полей.

Volet.com не обрабатывает эти поля и возвращает их без изменений в уведомлениях на Status URL и при перенаправлении клиента.

Типичные сценарии:

  • ID клиента
  • ID подписки
  • Внутренний номер счёта
  • Комментарий

Пример:

<input type="hidden" name="customer_id" value="12345">
<input type="hidden" name="subscription_id" value="sub_987">
<input type="hidden" name="invoice_no" value="INV-2026-001">
<input type="hidden" name="comment" value="Premium plan">

Субмерчанты​

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

Пример:

<input type="hidden" name="ac_submerchant_url" value="https://merchant.example.com">

Этот параметр предназначен для платёжных агрегаторов, маркетплейсов и платформ, которые обрабатывают платежи других мерчантов.

примечание

Все требования к комплаенсу, запрещённым видам деятельности и верификации, которые действуют для мерчантов, распространяются и на субмерчантов.

Переопределение URL​

Следующие параметры можно указать прямо в платёжном запросе:

  • ac_success_url
  • ac_success_url_method
  • ac_fail_url
  • ac_fail_url_method
  • ac_status_url
  • ac_status_url_method

Пример:

<input type="hidden" name="ac_success_url" value="https://merchant.example.com/payment-success">
<input type="hidden" name="ac_success_url_method" value="GET">
<input type="hidden" name="ac_fail_url" value="https://merchant.example.com/payment-failed">
<input type="hidden" name="ac_fail_url_method" value="GET">
<input type="hidden" name="ac_status_url" value="https://merchant.example.com/payment-status">
<input type="hidden" name="ac_status_url_method" value="POST">

Значения из запроса переопределяют URL по умолчанию, заданные для шлюза Hosted Checkout.

Это удобно, когда один шлюз Hosted Checkout используют несколько сайтов, магазинов, приложений, ботов или ИИ-агентов.

Так же можно задавать разные URL успеха, неудачи и уведомлений для разных заказов, не создавая несколько шлюзов Hosted Checkout.

Отключение подписей​

Параметр ac_sign необязателен, если цифровые подписи отключены в настройках Hosted Checkout.

Однако в рабочей среде мы настоятельно рекомендуем использовать подписи: они подтверждают подлинность запросов и защищают данные от подмены.

Запросы без подписи стоит использовать только для тестирования и разработки.

Справочник Hosted Checkout​

Параметры платёжного запроса​

Платёжный запрос — это HTML-форма, которую ваше приложение отправляет в Hosted Checkout.

Она содержит данные платежа, сведения о мерчанте, URL для перенаправления и необязательные параметры настройки, нужные для обработки платежа.

В таблице ниже перечислены все поддерживаемые параметры платёжного запроса.

ПараметрОбязательныйФорматОписаниеПримеры
ac_account_emailДаСтрокаEmail вашего аккаунта Volet.com.[email protected]
ac_sci_nameДаСтрока (макс. 50 символов)Название Hosted Checkout.My Store
ac_amountДаДесятичное числоСумма платёжного запроса. Количество знаков после запятой зависит от выбранной валюты. Лишние знаки автоматически отбрасываются.100.00, 49.0302, 0.12345678
ac_currencyДаКод валютыВалюта платёжного запроса.USD, EUR, BTC, ETH, USDT, USDC, XRP, TRX, LTC, TON, SOL
ac_order_idДаСтрока (макс. 64 символа; "A-z", "-", "_", "0-9")Уникальный идентификатор заказа мерчанта.123456, baf419d9-6c82-4175-b870-5541b0ff3794
ac_signУсловноHex-строка (SHA-256)Подпись запроса для проверки целостности платёжного запроса. Обязательна, если для Hosted Checkout включена проверка подписи запросов.36b4c9ad29b61d1c5996e3ef1a3af0c3194e19713613b6bf26a9b905b8019225
ac_psНетСтрока (ID платёжного метода)Платёжный метод, выбранный заранее при открытии Hosted Checkout.VOLET, USDTETHER, USD_COIN, BITCOIN, ETHEREUM, RIPPLE, TRON, LITECOIN, TON, SOL, BNB, MATIC (для POLYGON), AVAX
ac_ps_protocolУсловноСтрока (ID блокчейна или протокола)Заранее выбранная блокчейн-сеть. Обязателен, если ac_ps равен USDTETHER, USD_COIN или BNB; в остальных случаях необязателен.ETHEREUM, TRON, BINANCE_SMART_CHAIN, MATIC (для POLYGON), SOLANA, AVALANCHE, OPTIMISM, ARBITRUM, TON
ac_commentsНетСтрока (макс. 255 символов)Дополнительное описание платежа, которое видит клиент и которое нельзя изменить.Payment for Order #1234
ac_success_urlНетСтрока (макс. 100 символов)Переопределяет заданный Success URL.https://merchant.example.com/success
ac_success_url_methodНетGET, POSTHTTP-метод для перенаправления на Success URL. Переопределяет настройку Hosted Checkout.GET
ac_fail_urlНетСтрока (макс. 100 символов)Переопределяет заданный Failed URL.https://merchant.example.com/failed
ac_fail_url_methodНетGET, POSTHTTP-метод для перенаправления на Failed URL. Переопределяет настройку Hosted Checkout.POST
ac_status_urlНетСтрока (макс. 100 символов)Переопределяет заданный Status URL.https://merchant.example.com/status
ac_status_url_methodНетGET, POSTHTTP-метод для уведомлений на Status URL. Переопределяет настройку Hosted Checkout.POST
ac_client_langНетСтрока (код локали)Язык страницы Hosted Checkout.en
ac_submerchant_urlНетСтрока (макс. 100 символов)URL сайта субмерчанта. Используется в интеграциях для платформ и обязателен для отдельных категорий мерчантов.https://seller.example.com
Собственные поля (например, buyer_email, client_email)НетДо 10 строковых значений (макс. 100 символов каждое)Дополнительные поля мерчанта, которые возвращаются без изменений в уведомлениях на Status URL и при перенаправлении клиента. По ним можно сопоставлять платежи со своими заказами, клиентами, счетами и другими внутренними записями.[email protected], #INV-12345, user_1001

Пример​

<form method="POST" action="https://account.volet.com/api/public/payment-gateway">
<input type="hidden" name="ac_account_email" value="[email protected]">
<input type="hidden" name="ac_sci_name" value="My Store">
<input type="hidden" name="ac_amount" value="100.00">
<input type="hidden" name="ac_currency" value="USD">
<input type="hidden" name="ac_order_id" value="order_123456">
<input type="hidden" name="ac_sign" value="36b4c9ad29b61d1c5996e3ef1a3af0c3194e19713613b6bf26a9b905b8019225">

<input type="hidden" name="ac_ps" value="USDTETHER">
<input type="hidden" name="ac_ps_protocol" value="ETHEREUM">
<input type="hidden" name="ac_comments" value="Payment for Order #123456">

<input type="hidden" name="ac_success_url" value="https://merchant.example.com/payment-success">
<input type="hidden" name="ac_success_url_method" value="GET">
<input type="hidden" name="ac_fail_url" value="https://merchant.example.com/payment-failed">
<input type="hidden" name="ac_fail_url_method" value="GET">
<input type="hidden" name="ac_status_url" value="https://merchant.example.com/payment-status">
<input type="hidden" name="ac_status_url_method" value="POST">

<input type="hidden" name="ac_client_lang" value="en">
<input type="hidden" name="ac_submerchant_url" value="https://seller.example.com">

<!-- Custom fields -->
<input type="hidden" name="customer_id" value="customer_12345">
<input type="hidden" name="customer_email" value="[email protected]">
<input type="hidden" name="invoice_id" value="INV-2026-001">
<input type="hidden" name="subscription_id" value="sub_98765">
<input type="hidden" name="merchant_internal_id" value="seller_456">

<button type="submit">Pay with Volet.com</button>
</form>

Параметры успешного платежа​

После успешного платежа Hosted Checkout перенаправляет клиента на ваш Success URL и передаёт данные платежа заданным методом перенаправления.

В таблице ниже описаны все доступные параметры.

ПараметрФорматОписаниеПримеры
ac_src_walletСтрокаНомер кошелька клиента, с которого проведён платёж.USDT123456789012
ac_dest_walletСтрокаНомер кошелька мерчанта или кошелька для расчётов.USD123456789012
ac_amountДесятичное числоСумма платёжного запроса.100.00, 0.12500000
ac_merchant_amountДесятичное числоСумма, зачисленная на аккаунт мерчанта.100.00
ac_merchant_currencyКод валютыВалюта расчёта.USD, EUR, BTC, ETH, USDT, USDC, XRP, TRX, LTC, TON, SOL
ac_feeДесятичное числоКомиссия за обработку платежа.0.50
ac_buyer_amount_without_commissionДесятичное числоСумма, оплаченная клиентом без комиссий, которые платит клиент, если они есть.100.00
ac_buyer_amount_with_commissionДесятичное числоОбщая сумма, оплаченная клиентом, включая комиссии, которые платит клиент.100.50
ac_buyer_currencyКод валютыВалюта, в которой клиент провёл платёж.USD, EUR, BTC, ETH, USDT, USDC, XRP, TRX, LTC, TON, SOL, BNB, AVAX, POL
ac_transferUUIDУникальный идентификатор транзакции Volet.com.235f9d0b-b48f-462c-9949-621c4930490c
ac_sci_nameСтрокаНазвание Hosted Checkout.My Store
ac_start_dateYYYY-MM-DD HH:mm:ss (UTC)Дата и время создания платежа.2026-06-23 12:30:00
ac_order_idСтрокаИдентификатор заказа мерчанта из платёжного запроса.123456, baf419d9-6c82-4175-b870-5541b0ff3794
ac_psСтрока (ID платёжного метода)Платёжный метод, которым воспользовался клиент.VOLET, USDT, USDC, BTC, ETH, TRX, SOL
ac_transaction_statusСтатусИтоговый статус платежа. Возможные значения: PENDING, PROCESS, COMPLETED, CANCELED.COMPLETED
ac_buyer_emailСтрока (email)Email клиента, если доступен.[email protected]
ac_buyer_verifiedЛогическое значениеПоказывает, верифицирован ли аккаунт клиента.true, false
ac_commentsСтрокаКомментарий из платёжного запроса.Order #123456
Собственные поляСтрокаПоля мерчанта, возвращённые без изменений из платёжного запроса.customer_id, invoice_id, subscription_id

Пример​

<form method="POST" action="https://merchant.example.com/payment-success">
<input type="hidden" name="ac_src_wallet" value="USDT210987654321">
<input type="hidden" name="ac_dest_wallet" value="USD123456789012">
<input type="hidden" name="ac_amount" value="100.00">
<input type="hidden" name="ac_merchant_amount" value="99.50">
<input type="hidden" name="ac_merchant_currency" value="USD">
<input type="hidden" name="ac_fee" value="0.50">
<input type="hidden" name="ac_buyer_amount_without_commission" value="100.00">
<input type="hidden" name="ac_buyer_amount_with_commission" value="100.00">
<input type="hidden" name="ac_buyer_currency" value="USDT">
<input type="hidden" name="ac_transfer" value="235f9d0b-b48f-462c-9949-621c4930490c">
<input type="hidden" name="ac_sci_name" value="My Store">
<input type="hidden" name="ac_start_date" value="2026-06-23 12:30:00">
<input type="hidden" name="ac_order_id" value="order_123456">
<input type="hidden" name="ac_ps" value="VOLET">
<input type="hidden" name="ac_transaction_status" value="COMPLETED">
<input type="hidden" name="ac_buyer_email" value="[email protected]">
<input type="hidden" name="ac_buyer_verified" value="true">
<input type="hidden" name="ac_comments" value="Order #123456">
<!-- Custom fields -->
<input type="hidden" name="customer_id" value="customer_12345">
<input type="hidden" name="invoice_id" value="INV-2026-001">
<input type="hidden" name="subscription_id" value="sub_98765">
</form>

Параметры неудачного платежа​

Если платёж отменён или не прошёл, Hosted Checkout перенаправляет клиента на ваш Failed URL и передаёт данные платежа заданным методом перенаправления.

В таблице ниже описаны все доступные параметры.

ПараметрФорматОписаниеПримеры
ac_dest_walletСтрокаАккаунт мерчанта или кошелёк для расчётов.USD123456789012
ac_amountДесятичное числоСумма платёжного запроса.100.00, 49.95
ac_currencyКод валютыВалюта платёжного запроса.USD, EUR, BTC, ETH, USDT, USDC, XRP, TRX, LTC, TON, SOL
ac_sci_nameСтрокаНазвание Hosted Checkout.My Store
ac_order_idСтрокаИдентификатор заказа мерчанта из платёжного запроса.order_123456, baf419d9-6c82-4175-b870-5541b0ff3794
Собственные поляСтрокаПоля мерчанта, возвращённые без изменений из платёжного запроса.customer_id, invoice_id, subscription_id

Пример​

<form method="POST" action="https://merchant.example.com/payment-failed">
<input type="hidden" name="ac_dest_wallet" value="USD123456789012">
<input type="hidden" name="ac_amount" value="100.00">
<input type="hidden" name="ac_currency" value="USD">
<input type="hidden" name="ac_sci_name" value="My Store">
<input type="hidden" name="ac_order_id" value="order_123456">
<!-- Custom fields -->
<input type="hidden" name="customer_id" value="customer_12345">
<input type="hidden" name="invoice_id" value="INV-2026-001">
<input type="hidden" name="subscription_id" value="sub_98765">
</form>

Параметры уведомления о платеже​

Когда статус платежа меняется, Hosted Checkout отправляет уведомление на ваш Status URL заданным методом запроса (GET или POST).

Уведомление содержит все параметры успешного платежа и дополнительно подпись ac_hash.

ПараметрФорматОписаниеПримеры
ac_hashSHA-256-хеш (шестнадцатеричная строка)Подпись SHA-256, подтверждающая, что уведомление отправлено Volet.com и не было изменено при передаче.1cd6c127c5c49b6d5060cec4bdbf06608216c0c11cc76acebb546be0f7081afd

Как сформировать и проверить подпись, описано в разделе Проверка подписи уведомления.

Пример уведомления​

<form method="POST" action="https://merchant.example.com/status">
<input type="hidden" name="ac_src_wallet" value="USDT210987654321">
<input type="hidden" name="ac_dest_wallet" value="USD123456789012">
<input type="hidden" name="ac_amount" value="123.45">
<input type="hidden" name="ac_merchant_amount" value="123.55">
<input type="hidden" name="ac_merchant_currency" value="USD">
<input type="hidden" name="ac_fee" value="0.10">
<input type="hidden" name="ac_buyer_amount_without_commission" value="123.45">
<input type="hidden" name="ac_buyer_amount_with_commission" value="123.55">
<input type="hidden" name="ac_buyer_currency" value="USD">
<input type="hidden" name="ac_transfer" value="235f9d0b-b48f-462c-9949-621c4930490c">
<input type="hidden" name="ac_sci_name" value="My Shop">
<input type="hidden" name="ac_start_date" value="2026-06-23 12:30:00">
<input type="hidden" name="ac_order_id" value="123456">
<input type="hidden" name="ac_ps" value="VOLET">
<input type="hidden" name="ac_transaction_status" value="COMPLETED">
<input type="hidden" name="ac_buyer_email" value="[email protected]">
<input type="hidden" name="ac_buyer_verified" value="true">
<input type="hidden" name="ac_comments" value="Payment for order #123456">
<input type="hidden" name="ac_hash" value="1cd6c127c5c49b6d5060cec4bdbf06608216c0c11cc76acebb546be0f7081afd">
<!-- Custom fields -->
<input type="hidden" name="customer_id" value="98765">
<input type="hidden" name="invoice_id" value="INV-2026-001">
</form>