Документация API (v1.0.0) OpenAPI (Swagger)

Документация 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.

БАЗОВЫЙ URL https://visualpay.net/

Возврат по callback

Если при создании транзакции указан необязательный callback_url, страница оплаты перенаправит браузер плательщика на ваш URL, когда платёж достигнет финального статуса. Используйте один URL для всех исходов: успех и неудача различаются по параметру запроса status.

Параметры запроса, добавляемые к вашему URL

Шлюз добавляет к callback URL параметры из таблицы ниже, чтобы ваше приложение могло определить заказ и его итог без дополнительного вызова API.

Параметр Описание
order_id ID вашего заказа из запроса на создание транзакции, если он был передан.
status Итоговый статус платежа: confirmed, expired или cancelled (те же значения, что в методе «Проверить транзакцию»).
tracking_code UUID транзакции VisualPay для проверки.

Пример перенаправления

url
https://example.com/order?order_id=100001&status=confirmed&tracking_code=550e8400-e29b-41d4-a716-446655440000
Важно: Возврат по callback нужен только для удобства в браузере. Перед выполнением заказа ваш бэкенд всё равно должен подтвердить платёж через вебхук или метод «Проверить транзакцию». Если callback_url не указан, плательщик остаётся на странице оплаты VisualPay.

Время перенаправления: при подтверждённом платеже 3 секунды показывается сообщение об успехе, затем происходит переход. При истёкшем или отменённом платеже переход выполняется сразу.

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

Для работы с API мерчанта VisualPay каждый запрос нужно авторизовать API-ключом мерчанта. Создайте мерчанта в панели VisualPay и скопируйте API-ключ из его настроек.

Безопасность: Храните API-ключ в надёжном месте. Он показывается при создании, и его нельзя раскрывать в клиентском коде.

API-ключ мерчанта обязателен в каждом запросе.

Передавайте API-ключ мерчанта в HTTP-заголовке x-api-key во всех запросах к API.

http
x-api-key: YOUR_MERCHANT_API_KEY
GET /api/v1/merchant/currencies/list

Список поддерживаемых валют

Возвращает валюты и сети, включённые для авторизованного мерчанта.

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

bash
curl --location 'https://visualpay.net/api/v1/merchant/currencies/list' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

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

json
{
    "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"
}
GET /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.

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

bash
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'

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

json
{
    "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"
}
POST /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. Всегда проверяйте статус платежа на сервере через вебхук или метод «Проверить транзакцию» и не полагайтесь только на перенаправление.

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

bash
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"}'

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

json
{
    "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"
}
GET /api/v1/merchant/transaction/status

Проверить транзакцию

Поиск по tracking_code. Возвращаются только транзакции авторизованного мерчанта.

Параметры запроса

Поле Обязательный Тип Описание
tracking_code Да string Трек-код шлюза, полученный при создании транзакции

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

bash
curl --location 'https://visualpay.net/api/v1/merchant/transaction/status?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

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

json
{
    "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"
}
GET /api/v1/merchant/transaction/recheck

Перепроверить транзакцию

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

Параметры запроса

Поле Обязательный Тип Описание
tracking_code Да string Трек-код шлюза, полученный при создании транзакции

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

bash
curl --location 'https://visualpay.net/api/v1/merchant/transaction/recheck?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

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

json
{
    "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."
}
POST /api/v1/merchant/transaction/cancel

Отменить транзакцию

Отменить можно только транзакции со статусом pending.

Параметры запроса

Поле Обязательный Тип Описание
tracking_code Да string Трек-код шлюза для ожидающей транзакции, которую нужно отменить.

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

bash
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"}'

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

json
{
    "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."
}
GET /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.

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

bash
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'

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

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

Транзакция отменена.

Рекомендация: Когда плательщик вернётся на ваш сайт, вызовите метод «Проверить транзакцию» и убедитесь в итоговом статусе платежа, прежде чем выполнять заказ.