Tovanix
Tovanix

API виртуальных карт

Массово выпускайте и управляйте виртуальными картами Visa / Mastercard через API с пополнением USDT для подписок, рекламы и международных закупок.

  • Поиск BIN: доступные BIN, поддерживаемые регионы и диапазоны лимитов
  • Выпуск и пополнение: создавайте карты с выбранным BIN и пополняйте по мере необходимости
  • Управление: заморозка, разморозка, закрытие и безопасное получение реквизитов
  • Операции и вебхуки: история каждой операции и события авторизации и расчёта в реальном времени

Обзор

Открытый API виртуальных карт позволяет открывать карты, получать BIN, подробности, коды 3DS OTP, запрашивать транзакции, пополнять и закрывать карты. Также доступны баланс USD и отдельный постоянный адрес пополнения TRON. Все ответы имеют единую структуру JSON (code/message/data, code=0 — успех).

Базовый URL — адрес вашего шлюза (источник этого сайта). Префикс карт — /api/v1/vcard, учётной записи — /api/v1/account.

Все суммы в USD; открытие и пополнение оплачиваются с баланса USD платформы (только балансом). При недостатке средств возвращается ошибка.

Аутентификация и подпись

Чтение BIN, списка карт, транзакций, заказов, баланса и адреса пополнения принимает обычную пару ключей. Движение средств и конфиденциальные данные дополнительно требуют HMAC, временную метку и nonce против повторов: открытие, пополнение, закрытие, возврат баланса, заморозка/разморозка, полные подробности карты (details) и код 3DS (code). Утечки только обычного ключа недостаточно для движения средств или чтения конфиденциальных данных.

Войдите в консоль → Инструменты и настройки → Управление API → Создать ключ; скопируйте API Key и Secret Key (секрет показывается один раз).

Открытие, пополнение, закрытие, возврат баланса, заморозка/разморозка, полная карта с номером и CVV и код 3DS принимают только подписанные запросы; обычные ключи возвращают 401. Другие операции чтения не требуют подписи.

Баланс учётной записи

GET /api/v1/account/balance

Получите текущий баланс USD, по возможности с постоянным адресом пополнения TRON (deposit_address равен null при временной недоступности пула; баланс всё равно возвращается).

Постоянный адрес TRON

GET /api/v1/account/deposit-address

Получите/назначьте отдельный постоянный адрес пополнения TRON (USDT/TRX·TRC20). Заказ не нужен — любая сумма автоматически преобразуется в USD и зачисляется; подходит для автопополнения через API. После назначения адрес постоянный.

Поля ответа

Отправьте USDT или TRX на адрес; после подтверждения сканером блоков сумма автоматически преобразуется в USD по текущему курсу и зачисляется на баланс платформы — обратный вызов не нужен.

Состояние сервисов

GET /api/v1/vcard/info

Возвращает, включён ли сервис виртуальных карт, и текущий баланс USD.

Поля ответа

Если баланс аккаунта нельзя прочитать, интерфейс возвращает HTTP 503 вместо balance: 0. При 503 повторите позже и не считайте баланс нулевым.

BIN карт

GET /api/v1/vcard/bins

Возвращает список BIN карт. Комиссии — итоговые цены с наценкой платформы по уровню API за расходы последних 30 дней (больше расходы — ниже ставка). can_open=false отмечает BIN только для пополнения существующих карт, без открытия новых.

Открыть карту Подписано

POST /api/v1/vcard/cards

Создайте карту. Система списывает с баланса USD комиссию открытия, пополнения и сумму на карту; заказ обрабатывается асинхронно через очередь.

Поля ответа

Открытие асинхронное: после ответа с order_id и status=queued опрашивайте подробности заказа до completed. При ошибке средства автоматически возвращаются на баланс.

При тайм-ауте или обрыве соединения списание уже могло произойти. Не повторяйте с новым номером: отправьте тот же out_trade_no (существующий заказ возвращается без изменений и нового списания) либо проверьте через GET /api/v1/vcard/orders/by-trade-no/:out_trade_no. Запросы без out_trade_no не защищены: повтор может списать деньги ещё раз.

Список карт

GET /api/v1/vcard/cards

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

Поля ответа

Список карт возвращает только поля таблицы выше. can_return и fee_return доступны лишь для некоторых BIN; при их отсутствии считайте возврат баланса неподдерживаемым.

Подробности карты Подписано

GET /api/v1/vcard/cards/:id/details

Возвращает конфиденциальные данные карты открытым текстом: полный номер, CVV, срок, держатель. Запрашивать можно только свои карты.

Поля ответа

Примечание: таблица перечисляет гарантированные платформой поля; в ответе могут быть и другие поля — ориентируйтесь на фактический ответ.

Конечная точка возвращает полный номер и CVV — вызывайте только с доверенного сервера, не раскрывайте во фронтенде или журналах.

Транзакции

GET /api/v1/vcard/cards/:id/transactions

Возвращает транзакции/выписки карты (расход, пополнение и др.); при каждом запросе последние операции синхронизируются в реальном времени.

Поля ответа

Примечание: таблица перечисляет гарантированные платформой поля; в ответе могут быть и другие поля — ориентируйтесь на фактический ответ.

Код OTP Подписано

GET /api/v1/vcard/cards/:id/code

Получите последний код 3DS OTP карты для подтверждения оплаты.

Пополнить Подписано

POST /api/v1/vcard/cards/:id/recharge

Пополните существующую карту. С баланса USD списываются сумма и комиссия; обработка асинхронная через очередь.

Поля ответа

При тайм-ауте или обрыве соединения списание уже могло произойти. Не повторяйте с новым номером: отправьте тот же out_trade_no (существующий заказ возвращается без изменений и нового списания) либо проверьте через GET /api/v1/vcard/orders/by-trade-no/:out_trade_no. Запросы без out_trade_no не защищены: повтор может списать деньги ещё раз.

Отмена Подписано

POST /api/v1/vcard/cards/:id/cancel

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

Возврат баланса Подписано

POST /api/v1/vcard/cards/:id/return

Верните остаток на баланс учётной записи без закрытия карты. Комиссия удерживается из возвращаемой суммы, чистая сумма зачисляется автоматически. Поддерживается частью BIN: доступно при can_return=true в списке; fee_return — комиссия возврата этого BIN.

Одновременно допускается один возврат на карту. Повторная отправка во время обработки возвращает 400 — ждите конечного состояния, а не повторяйте запрос.

Заблокировать / Разблокировать Подписано

POST /api/v1/vcard/cards/:id/freeze

Заморозьте или разморозьте карту. Каждая операция имеет небольшую комиссию (status_fee в списке). Доступно при can_freeze=true; возвращает 400, если состояние уже нужное или предыдущая операция ещё выполняется.

Автопополнение (правила баланса) Подписано

GET /api/v1/vcard/balance-rules

GET /api/v1/vcard/cards/:id/balance-rule

PUT /api/v1/vcard/cards/:id/balance-rule

DELETE /api/v1/vcard/cards/:id/balance-rule

POST /api/v1/vcard/cards/:id/balance-rule/resume

Автоматически пополняет карту, когда её баланс опускается ниже заданной суммы, или только присылает напоминание. На каждую карту одно правило; PUT создаёт или заменяет его. Автопополнение идёт тем же путём списания, что и ручное (те же лимиты и комиссии), и запускается при изменении баланса карты или при ежеминутной проверке.

Ограничения безопасности: обязательны число автопополнений в день (1–10, по часовому поясу аккаунта) и месячный лимит суммы. Правило приостанавливается и уведомляет вас, если карта заморожена или закрывается, эмитент отклонил операцию из-за мошенничества, 3 операции подряд отклонены или 3 раза подряд не хватило баланса аккаунта. Вызовите resume, чтобы возобновить (правила, приостановленные платформой, сами не возобновить).

API-ключи с дневным лимитом списаний не могут создавать или возобновлять автопополнение (403, бизнес-код 4035): платформа списывает автопополнения в фоне, вне лимита ключа. Правила только с напоминанием не затронуты.

Подписки

GET /api/v1/vcard/subscriptions

Регулярные списания, найденные в операциях ваших активных карт (только чтение, считается на лету): повторяющиеся списания одного продавца примерно раз в неделю, месяц или год считаются подпиской. Чтобы остановить, заморозьте или закройте карту.

Разрешённые продавцы Подписано

GET /api/v1/vcard/merchant-locks

GET /api/v1/vcard/cards/:id/merchant-lock

PUT /api/v1/vcard/cards/:id/merchant-lock

DELETE /api/v1/vcard/cards/:id/merchant-lock

Задаёт продавцов, у которых можно пользоваться картой. Если появилась операция у другого продавца, карта автоматически замораживается (одна комиссия за заморозку) или вы только получаете уведомление. Проверяются только операции после сохранения, и заморозка происходит после факта — первая операция вне списка уже авторизована.

Группы карт

GET /api/v1/vcard/groups

POST /api/v1/vcard/groups

PUT /api/v1/vcard/groups/:gid

DELETE /api/v1/vcard/groups/:gid

POST /api/v1/vcard/cards/group

Объединяйте карты в группы, у каждой можно задать месячный бюджет: одно уведомление при 80 % и одно при превышении; операции никогда не блокируются. Карта состоит не более чем в одной группе; group_id 0 убирает её из группы. До 20 групп.

Месячная выписка

GET /api/v1/vcard/bill/export

Операции по картам за месяц, при желании по одной карте или группе, от старых к новым. Входят только операции за время, когда карта была у вас; если строк больше 20 000, вернётся 400 — выгружайте по картам или группам.

Список заказов

GET /api/v1/vcard/orders

Постраничный список ваших заказов открытия/пополнения/закрытия.

Подробности заказа

GET /api/v1/vcard/orders/:id

Запросите ход отдельного заказа для опроса результата открытия/пополнения.

Возвращает объект заказа с теми же полями, что в «Запросе заказов».

Поиск по собственному номеру заказа

GET /api/v1/vcard/orders/by-trade-no/:out_trade_no

Ищет по out_trade_no, переданному при выпуске или пополнении карты. Ответ совпадает со сведениями о заказе. Возвращает 404, если номера нет.

Обновить примечание

PUT /api/v1/vcard/cards/:id/remark

Задайте примечание карты (до 60 символов).

Push через Webhook

При событиях карты (открытие/пополнение/закрытие, транзакция, код 3DS) платформа отправляет HTTP POST (JSON) на ваш адрес — опрос не нужен. Настройка: Консоль → Виртуальная карта → Интеграция API (включение, URL, секрет подписи, события; если ничего не отмечено — все события).

Условия доставки: публичный https URL; плоский JSON со всеми значениями-строками. Ответ 2xx — успех, иначе повторы с задержкой 30s → 1m → 2m → 5m → 10m, до 10 попыток. Повторы имеют один notify_id — устраняйте дубли по нему.

Общие поля всех событий; специальные поля ниже:

Проверка: все непустые поля, кроме "sign", сортируются по ключу ASC, объединяются как k=v&k2=v2, вычисляется HMAC-SHA256 (hex, нижний регистр) с вашим секретом и сравнивается с sign. Также sign_ts должен быть в пределах ±5 минут и nonce ещё не встречаться. При любой ошибке отклоняйте с 401.

События и специальные поля:

Часто задаваемые вопросы

Как скоро можно пользоваться картой и где её принимают?

Реквизиты возвращаются за несколько секунд после выпуска. Карта сразу работает там, где принимают онлайн-платежи Visa / Mastercard: обычно для подписок ИИ, пополнения рекламных платформ и международной торговли.

Как выяснить причину отклонения операции?

Запросите историю операций для получения кода причины отказа этой авторизации. Чаще всего это недостаточный баланс, ограниченная категория магазина или блокировка контроля рисков. События авторизации и расчёта также поступают через вебхуки для сверки.

Связанные страницы: Виртуальные карты · Документация API · Мультичейн-платежи в криптовалюте

Загрузка…