Документация API криптоплатежей
Это полный справочник REST API криптоплатёжного шлюза VisualPay. С его помощью можно создавать транзакции, принимать платежи в USDT, USDC, ETH, BNB и TON в любой поддерживаемой сети, отслеживать статус в блокчейне и получать вебхуки. Всё это делается из вашего бэкенда, без промежуточной страницы оплаты на стороне шлюза.
Каждый метод ниже авторизуется одним API-ключом мерчанта, возвращает JSON и вызывается из любого языка или фреймворка. Не нужно ставить SDK или поддерживать плагин.
Начало работы
Чтобы подключить криптоплатёжный шлюз VisualPay, достаточно одного POST-запроса. Вы передаёте сумму заказа в USD, монету и сеть, в которых хотите получить оплату, а API возвращает адрес для платежа, точную сумму в USDT (или другой монете) и трек-код, который можно сохранить вместе с заказом.
Интеграция с VisualPay позволяет вашему бизнесу принимать платежи в криптовалюте. Чтобы провести платёж, создайте транзакцию и перенаправьте пользователя на страницу оплаты из ответа. Мониторинг блокчейна берёт на себя VisualPay, а вы можете опрашивать статус или сверять данные в панели мерчанта.
При создании транзакции можно дополнительно передать callback_url, чтобы вернуть плательщика на ваш сайт после успешной или неуспешной оплаты. VisualPay добавляет к этому URL параметры запроса order_id (если он был передан), status и tracking_code.
https://visualpay.net/
Возврат по callback
Если при создании транзакции указан необязательный callback_url, страница оплаты перенаправит браузер плательщика на ваш URL, когда платёж достигнет финального статуса. Используйте один URL для всех исходов: успех и неудача различаются по параметру запроса status.
Параметры запроса, добавляемые к вашему URL
Шлюз добавляет к callback URL параметры из таблицы ниже, чтобы ваше приложение могло определить заказ и его итог без дополнительного вызова API.
| Параметр | Описание |
|---|---|
order_id |
ID вашего заказа из запроса на создание транзакции, если он был передан. |
status |
Итоговый статус платежа: confirmed, expired или cancelled (те же значения, что в методе «Проверить транзакцию»). |
tracking_code |
UUID транзакции VisualPay для проверки. |
Пример перенаправления
https://example.com/order?order_id=100001&status=confirmed&tracking_code=550e8400-e29b-41d4-a716-446655440000
callback_url не указан, плательщик остаётся на странице оплаты VisualPay.
Время перенаправления: при подтверждённом платеже 3 секунды показывается сообщение об успехе, затем происходит переход. При истёкшем или отменённом платеже переход выполняется сразу.
Аутентификация
Для работы с API мерчанта VisualPay каждый запрос нужно авторизовать API-ключом мерчанта. Создайте мерчанта в панели VisualPay и скопируйте API-ключ из его настроек.
API-ключ мерчанта обязателен в каждом запросе.
Передавайте API-ключ мерчанта в HTTP-заголовке x-api-key во всех запросах к API.
x-api-key: YOUR_MERCHANT_API_KEY
/api/v1/merchant/currencies/list
Список поддерживаемых валют
Возвращает валюты и сети, включённые для авторизованного мерчанта.
Пример запроса
curl --location 'https://visualpay.net/api/v1/merchant/currencies/list' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'
Пример ответа
{
"status": 200,
"data": [
{
"currency_name": "Tether",
"currency_symbol": "USDT",
"currency_type": "stable",
"price_in_usdt": 1,
"icon": "",
"supported_networks": [
{
"network_name": "TRON (TRC20)",
"network_symbol": "TRX",
"network_code": "trc20",
"network_fee": 1,
"minimum_pay_usd": 5,
"maximum_pay_usd": 10000,
"max_ttl": 30,
"icon": ""
}
]
}
],
"message": "success"
}
/api/v1/merchant/transaction/list
Список транзакций
Транзакции мерчанта с постраничной выдачей. Необязательные фильтры: перечисление status, диапазон дат (не более 30 дней).
Параметры запроса
| Поле | Обязательный | Тип | Описание |
|---|---|---|---|
limit |
Нет | integer | Записей на странице (1–50) |
page |
Нет | integer | Номер страницы |
from_date |
Нет | string (date) | Дата начала (Y-m-d). Обязательна вместе с to_date. Диапазон не более 30 дней. |
to_date |
Нет | string (date) | Дата окончания (Y-m-d). Обязательна вместе с from_date. Диапазон не более 30 дней. |
status |
Нет | enum | Необязательный. Допустимые значения: pending, confirmed, expired, cancelled. |
Пример запроса
curl --location 'https://visualpay.net/api/v1/merchant/transaction/list?limit=50&page=1&from_date=2026-07-01&to_date=2026-07-20&status=pending' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'
Пример ответа
{
"status": 200,
"data": {
"items": [
{
"order_id": 1001,
"status": "pending",
"tracking_code": "AbC12XyZ",
"payment_url": "https://pay.visualpay.net/AbC12XyZ",
"currency_code": "usdt_trc20",
"currency_name": "Tether",
"network_code": "trc20",
"network_name": "TRON (TRC20)",
"pay_amount": "10.00000000",
"amount_usd": "10.00000000",
"platform_share": "0.20000000",
"merchant_share": "9.80000000",
"payment_fee_percent": 1,
"payment_tolerance_percent": 1,
"paid_amount": "",
"is_canceled_by_user": false,
"tx_id": "",
"tx_explorer_url": "",
"email": "",
"comment": "",
"paid_at": 0,
"created_at": 0,
"expired_at": 0
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 120,
"last_page": 3
}
},
"message": "success"
}
/api/v1/merchant/transaction/create
Создать транзакцию
Создаёт новый криптоплатёж.
amount_usd: сумма к оплате в USD/USDT. Значение должно быть не меньше minimum_pay_usd и не больше maximum_pay_usd.
ttl: время жизни в минутах, в течение которого транзакция отслеживается. Значение не должно превышать max_ttl.
order_id: необязательный. Если передаёте этот параметр, он должен быть 6-значным числом.
email: необязательный.
comment: необязательный.
callback_url: необязательный. Публичный HTTPS URL на вашем сайте. Если он указан, страница оплаты вернёт плательщика после финального статуса (confirmed, expired или cancelled) и добавит параметры запроса order_id (если был передан), status и tracking_code.
Пример:
https://example.com/order?order_id=100001&status=confirmed&tracking_code=550e8400-e29b-41d4-a716-446655440000
Параметры запроса
| Поле | Обязательный | Тип | Описание |
|---|---|---|---|
currency_symbol |
Да | string | Символ валюты, включённой для вашего мерчанта (например, USDT, ETH). |
network_code |
Да | string | Код сети для выбранной валюты (например, TRC20, ERC20, BEP20). |
amount_usd |
Да | number | Сумма в USD/USDT |
ttl |
Да | integer | Время жизни в минутах, в течение которого транзакция отслеживается. Не должно превышать max_ttl валюты. |
order_id |
Нет | integer | Необязательный. Если указан, должен быть 6-значным числом. |
email |
Нет | string (email) | Необязательный. Email плательщика. |
comment |
Нет | string | Необязательный. Комментарий плательщика. |
callback_url |
Нет | string (uri) | Необязательный. Когда плательщик завершит оплату на странице оплаты или она не пройдёт, VisualPay перенаправит его браузер на этот HTTPS URL с параметрами запроса order_id (если был передан при создании), status и tracking_code. Используйте один URL для всех исходов и различайте результат по параметру status. Всегда проверяйте статус платежа на сервере через вебхук или метод «Проверить транзакцию» и не полагайтесь только на перенаправление. |
Пример запроса
curl --location 'https://visualpay.net/api/v1/merchant/transaction/create?currency_symbol=value&network_code=value&amount_usd=value&ttl=value&order_id=value&email=value&comment=value&callback_url=value' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"currency_symbol":"USDT","network_code":"trc20","amount_usd":25.5,"ttl":15,"order_id":100001,"email":"payer@example.com","comment":"Invoice #1001","callback_url":"https://example.com/order"}'
Пример ответа
{
"status": 200,
"data": {
"payment_url": "http://127.0.0.1:6131/payment/AbC12XyZ",
"tracking_code": "AbC12XyZ",
"status": "pending",
"order_id": 1001,
"currency_name": "Tether",
"currency_symbol": "USDT",
"network": "tron",
"network_code": "trc20",
"network_name": "TRON (TRC20)",
"amount_usd": "25.50000000",
"pay_amount": "25.50000000",
"platform_share": "0.51000000",
"merchant_share": "24.99000000",
"payment_fee_percent": 1,
"payment_tolerance_percent": 1,
"wallet_address": "TXyz...",
"qr_code": "",
"expired_at": 0
},
"message": "success"
}
/api/v1/merchant/transaction/status
Проверить транзакцию
Поиск по tracking_code. Возвращаются только транзакции авторизованного мерчанта.
Параметры запроса
| Поле | Обязательный | Тип | Описание |
|---|---|---|---|
tracking_code |
Да | string | Трек-код шлюза, полученный при создании транзакции |
Пример запроса
curl --location 'https://visualpay.net/api/v1/merchant/transaction/status?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'
Пример ответа
{
"status": 200,
"data": {
"order_id": 1001,
"status": "pending",
"tracking_code": "AbC12XyZ",
"payment_url": "https://pay.visualpay.net/AbC12XyZ",
"currency_code": "usdt_trc20",
"currency_name": "Tether",
"network_code": "trc20",
"network_name": "TRON (TRC20)",
"pay_amount": "10.00000000",
"amount_usd": "10.00000000",
"platform_share": "0.20000000",
"merchant_share": "9.80000000",
"payment_fee_percent": 1,
"payment_tolerance_percent": 1,
"paid_amount": "",
"is_canceled_by_user": false,
"tx_id": "",
"tx_explorer_url": "",
"email": "",
"comment": "",
"paid_at": 0,
"created_at": 0,
"expired_at": 0
},
"message": "success"
}
/api/v1/merchant/transaction/recheck
Перепроверить транзакцию
Повторно проверяет платёж в блокчейне для истёкшей или отменённой транзакции авторизованного мерчанта. Поиск по tracking_code.
Параметры запроса
| Поле | Обязательный | Тип | Описание |
|---|---|---|---|
tracking_code |
Да | string | Трек-код шлюза, полученный при создании транзакции |
Пример запроса
curl --location 'https://visualpay.net/api/v1/merchant/transaction/recheck?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'
Пример ответа
{
"status": 200,
"data": {
"order_id": 1001,
"status": "pending",
"tracking_code": "AbC12XyZ",
"payment_url": "https://pay.visualpay.net/AbC12XyZ",
"currency_code": "usdt_trc20",
"currency_name": "Tether",
"network_code": "trc20",
"network_name": "TRON (TRC20)",
"pay_amount": "10.00000000",
"amount_usd": "10.00000000",
"platform_share": "0.20000000",
"merchant_share": "9.80000000",
"payment_fee_percent": 1,
"payment_tolerance_percent": 1,
"paid_amount": "",
"is_canceled_by_user": false,
"tx_id": "",
"tx_explorer_url": "",
"email": "",
"comment": "",
"paid_at": 0,
"created_at": 0,
"expired_at": 0
},
"message": "Transaction confirmed successfully."
}
/api/v1/merchant/transaction/cancel
Отменить транзакцию
Отменить можно только транзакции со статусом pending.
Параметры запроса
| Поле | Обязательный | Тип | Описание |
|---|---|---|---|
tracking_code |
Да | string | Трек-код шлюза для ожидающей транзакции, которую нужно отменить. |
Пример запроса
curl --location 'https://visualpay.net/api/v1/merchant/transaction/cancel?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"tracking_code":"AbC12XyZ"}'
Пример ответа
{
"status": 200,
"data": {
"order_id": 1001,
"status": "pending",
"tracking_code": "AbC12XyZ",
"payment_url": "https://pay.visualpay.net/AbC12XyZ",
"currency_code": "usdt_trc20",
"currency_name": "Tether",
"network_code": "trc20",
"network_name": "TRON (TRC20)",
"pay_amount": "10.00000000",
"amount_usd": "10.00000000",
"platform_share": "0.20000000",
"merchant_share": "9.80000000",
"payment_fee_percent": 1,
"payment_tolerance_percent": 1,
"paid_amount": "",
"is_canceled_by_user": false,
"tx_id": "",
"tx_explorer_url": "",
"email": "",
"comment": "",
"paid_at": 0,
"created_at": 0,
"expired_at": 0
},
"message": "Transaction cancelled successfully."
}
/api/v1/merchant/withdrawals/list
Список выводов
История выводов с постраничной выдачей. Необязательные фильтры: перечисление status, диапазон дат (не более 30 дней).
Параметры запроса
| Поле | Обязательный | Тип | Описание |
|---|---|---|---|
limit |
Нет | integer | Записей на странице (1–50) |
page |
Нет | integer | Номер страницы |
from_date |
Нет | string (date) | Дата начала (Y-m-d). Обязательна вместе с to_date. Диапазон не более 30 дней. |
to_date |
Нет | string (date) | Дата окончания (Y-m-d). Обязательна вместе с from_date. Диапазон не более 30 дней. |
status |
Нет | enum | Необязательный. Допустимые значения: pending, processing, confirmed. |
Пример запроса
curl --location 'https://visualpay.net/api/v1/merchant/withdrawals/list?limit=50&page=1&from_date=2026-07-01&to_date=2026-07-20&status=pending' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'
Пример ответа
{
"status": 200,
"data": {
"items": [
{
"tracking_code": "49e9f567-8c2a-4b1d-9f3e-2a1b0c9d8e7f",
"currency_name": "Tether",
"network_name": "TRON (TRC20)",
"destination_address": "TXyz...",
"amount_usd": "$98.50",
"status": "Processing",
"tx_id": "",
"tx_explorer_url": "",
"created_at": 0
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 120,
"last_page": 3
}
},
"message": "success"
}
Статусы транзакций
Статус транзакции показывает текущее состояние платежа. Возможные значения:
pending
Ожидается платёж в блокчейне.
confirmed
Платёж успешно завершён.
expired
Время на оплату истекло, платёж не завершён.
cancelled
Транзакция отменена.