API виртуальных карт: как автоматизировать выпуск карт через код

Зачем нужен API выпуска карт

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

• Автоматически создавайте карту под каждую сущность — например, когда в CRM появляется новый клиент.
• Пополняйте карты по расписанию или когда баланс падает.
• Мгновенно замораживайте карты, когда исчерпан бюджет или закончился договор.
• Синхронизируйте транзакции с бухгалтерией и отчётностью.
• Реагируйте на события в реальном времени через вебхуки, а не опросом.

API делает то же, что и личный кабинет, только с вашего сервера. Каждая выпущенная карта и каждое пополнение оплачиваются с баланса аккаунта, который вы пополняете криптовалютой и который всегда хранится в USDT.

Как получить доступ к API виртуальных карт

Доступ — в три шага:

1. Создайте ключ. Откройте раздел доступа к API в личном кабинете и сгенерируйте ключ. Ключи начинаются с sk_live_.
2. Добейтесь активации. Подтвердите email и сделайте первое пополнение, затем попросите поддержку (через тикет в кабинете) включить API для вашего аккаунта.
3. Сделайте запрос. Проверьте баланс, затем выпустите первую карту.

Пока аккаунт не готов, корректный ключ получает ответ 403. Код ошибки onboarding_incomplete будет возвращаться, пока вы не подтвердите email и не сделаете первое пополнение, а затем api_not_enabled — пока доступ к API не включат.

Отдельной песочницы и официальных SDK нет. Вы вызываете REST API напрямую любым HTTP-клиентом: интеграция получается простой, но каждый вызов — боевой. Тестируйте на небольших суммах.

Основы: базовый URL, авторизация и формат

• Базовый URL: https://usdtcryptocard.com/api/v1
• Авторизация: передавайте ключ как Bearer-токен в заголовке Authorization каждого запроса.
• Формат: JSON по HTTPS. Суммы — в долларах США с двумя знаками после запятой. Время — ISO 8601 в UTC.
• Пагинация: эндпоинты списков принимают page и per_page.

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

Первый запрос

Проверка баланса — безопасный первый запрос:

curl https://usdtcryptocard.com/api/v1/wallet/balance \
  -H "Authorization: Bearer sk_live_..."

В ответе — баланс в USDT, пополнения в обработке и сумма на ваших картах:

{
  "balance": 1312.5,
  "currency": "USDT",
  "pending_deposits": 500.0,
  "cards_active": 8,
  "cards_total_balance": 2450.0
}

Эндпоинты

В API 15 эндпоинтов для шести ресурсов.

Все параметры и примеры ответов — в документации API.

Выпуск карты из кода

При создании карты в одном запросе выбирается BIN и карта пополняется с баланса. Поля:

• bin_id (обязательно): BIN для выпуска. Варианты можно получить через GET /bins.
• amount (обязательно): начальная сумма в USD, списывается с баланса. Минимум $50, комиссия $1 за выпуск списывается сверху.
• label: ваше название карты.
• spending_limit: лимит трат в USD.
• allowed_categories: категории продавцов, где можно использовать карту, например реклама или софт. Всё остальное отклоняется.
• auto_freeze_at: автоматически замораживать карту, когда баланс опускается ниже этой суммы.
• metadata: пары ключ-значение для вашего учёта.

Тот же запрос на Node.js:

const res = await fetch('https://usdtcryptocard.com/api/v1/cards', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.USDTCC_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    bin_id: '491653',
    amount: 500,
    label: 'Meta Ads - Campaign 12',
    spending_limit: 2000,
    allowed_categories: ['advertising'],
    metadata: { campaign: 'fall_2026' },
  }),
});
const card = await res.json();

Успешный вызов возвращает 201 с объектом карты: её id, BIN, платёжной системой, последними четырьмя цифрами, статусом, балансом, а также вашими label и metadata. Полный номер и CVV в сводку намеренно не входят.

Как безопасно получить номер карты

GET /cards/{card_id}/details возвращает полный номер карты, CVV и срок действия. Обращайтесь с этим как с конфиденциальными данными: никогда не логируйте ответ и не храните его без шифрования, а запрашивайте только тогда, когда действительно нужно передать реквизиты человеку или на страницу оплаты. У этого эндпоинта более жёсткий лимит запросов, чем у остальных.

Пополнение, заморозка и закрытие

• Пополнить: POST /cards/{card_id}/fund с полем amount переводит деньги с баланса на карту. Ими можно пользоваться сразу.
• Вернуть средства: POST /cards/{card_id}/withdraw возвращает баланс карты в кошелёк.
• Приостановить: POST /cards/{card_id}/freeze блокирует все операции, сохраняя баланс. unfreeze снова включает карту.
• Закрыть: DELETE /cards/{card_id} безвозвратно закрывает карту и возвращает остаток в кошелёк. Отменить это нельзя.

Для действий через API действуют те же комиссии, что и в кабинете: $1 за выпуск карты, $0.30 за одобренную операцию (отказы бесплатно), а пополнение карт с баланса бесплатно. Пополнения аккаунта до $300 облагаются комиссией 2%, от $300 — без комиссии. См. раздел с тарифами.

Вебхуки

Вместо опроса зарегистрируйте HTTPS-эндпоинт через POST /webhooks, перечислив нужные события (или ["*"] для всех). Доступные события:

• card.created, card.frozen, card.unfrozen, card.terminated, card.funded
• transaction.authorized, transaction.settled, transaction.declined, transaction.refunded
• 3ds.challenge
• deposit.pending, deposit.confirmed

Каждая доставка подписывается HMAC-SHA256 секретом вашего эндпоинта; если вы не укажете секрет, он будет сгенерирован автоматически. Прежде чем доверять содержимому, пересчитайте подпись по сырому телу запроса и сравните за постоянное время:

import crypto from 'node:crypto';

export function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Разбирайте JSON только после успешной проверки и делайте обработчик идемпотентным на случай, если событие придёт больше одного раза.

Ошибки и лимиты запросов

Любой ответ, отличный от 2xx, содержит JSON с постоянным кодом error, по которому можно ветвить логику, и понятным человеку message. Встречаются коды 400 (некорректные параметры), 401 (ключ отсутствует или недействителен), 403 (аккаунт не готов или API не включён), 404 (не найдено) и 429 (превышен лимит запросов).

Лимиты считаются для каждого API-ключа:

Получив 429, подождите и повторите запрос с экспоненциальной задержкой.

Советы для надёжной интеграции

• Храните id карты, а не её номер. Запрашивайте реквизиты по мере необходимости.
• Используйте metadata и label, чтобы связывать карты со своими записями — например, с ID клиента или кампанией.
• Предпочитайте вебхуки опросу для транзакций и проверок 3D Secure.
• Держите запас на картах, с которых идут регулярные списания, или используйте auto_freeze_at и fund для автоматического управления балансами.
• Учитывайте лимиты. Лимиты тарифа аккаунта продолжают действовать: тариф Virtual допускает $5,000 на операцию и $20,000 в месяц, а у Platinum, который открывается одним пополнением от $300, лимитов на траты нет.

Если вы управляете картами для команды без написания кода, см. виртуальные карты для команд. Для рекламных аккаунтов — статья виртуальные карты для рекламы. Готовы начать? Создайте аккаунт.

Частые вопросы

Что такое API виртуальных карт?

Это интерфейс, через который софт автоматически создаёт платёжные карты и управляет ими. В USDT Crypto Card это REST API с JSON по HTTPS и авторизацией секретным ключом sk_live_.

Есть ли песочница или SDK?

Нет. Песочницы и официальных SDK нет. Вы вызываете REST API напрямую любым HTTP-клиентом, и каждый вызов боевой, поэтому тестируйте на небольших суммах.

Почему новый API-ключ возвращает 403?

Аккаунт ещё не готов. onboarding_incomplete означает, что нужно подтвердить email и сделать первое пополнение. api_not_enabled означает, что поддержка ещё не включила доступ к API.

Как защищены вебхуки?

Каждая доставка подписывается HMAC-SHA256 секретом вашего эндпоинта. Пересчитайте подпись по сырому телу и сравните её за постоянное время, прежде чем доверять содержимому.

Карты через API стоят столько же, сколько через кабинет?

Да. Действуют те же комиссии: $1 за карту, $0.30 за одобренную операцию, бесплатное пополнение карт с баланса и комиссия 2% за пополнение аккаунта до $300.