Документация API — CryptoTopCard API Виртуальных Карт

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

API-ключи & Аутентификация

Все API-запросы требуют токен Bearer. Сгенерируйте API-ключ в Панель → Настройки → API-ключи.

Безопасность API-ключа

Никогда не раскрывайте ключ в клиентском коде. Используйте переменные окружения. Ключи с префиксом sk_live_ — продакшн, sk_test_ — sandbox.

request-headers

Authorization: Bearer sk_live_your_api_key_here
Content-Type: application/json
X-Idempotency-Key: optional-unique-key-for-safe-retries

Лимиты запросов

1,000

Запросов / Минуту

50

Создание карт / Минуту

10,000

Запросов / Час

Коды ошибок

error-response.json

{
  "error": "insufficient_funds",
  "message": "Your wallet balance is too low to fund this card.",
  "code": 400,
  "request_id": "req_7f8a9b2c3d4e"
}

200

Запрос выполнен

201

Ресурс создан

400

Неверные параметры запроса

401

Отсутствует или неверный API-ключ

404

Ресурс не найден

429

Превышен лимит запросов

Карты

Управление картами

Создавайте, управляйте и контролируйте виртуальные карты Visa & Mastercard. Каждая карта изолирована со своим балансом, лимитами и жизненным циклом.

POST /cards Выпустить новую виртуальную карту

Тело запроса

Параметр	Тип		Описание
bin_id	string	required	Идентификатор BIN (напр. `491653`). Используйте `GET /bins` для списка доступных BIN.
amount	number	required	Начальная сумма пополнения в USD. Мин: $1.00, Макс: $5,000.00
label	string	optional	Пользовательская метка для карты (макс. 64 символа)
spending_limit	number	optional	Месячный лимит расходов в USD. По умолчанию — максимум BIN.
allowed_categories	string[]	optional	Категории MCC для белого списка (напр. `["advertising", "software"]`)
auto_freeze_at	number	optional	Автозаморозка при падении баланса ниже этой суммы
metadata	object	optional	Пары ключ-значение для внутреннего отслеживания (макс. 20 ключей)

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

curl

curl -X POST https://api.cryptotopcard.com/v1/cards \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bin_id": "491653",
    "amount": 500,
    "label": "Meta Ads Campaign #12",
    "spending_limit": 2000,
    "allowed_categories": ["advertising"],
    "metadata": {"campaign": "spring_2026"}
  }'

Ответ 201 Created

response.json

{
  "id": "card_8xK2m9Lp4q",
  "bin_id": "491653",
  "network": "visa",
  "last4": "2039",
  "status": "active",
  "balance": 500.00,
  "spending_limit": 2000.00,
  "label": "Meta Ads Campaign #12",
  "allowed_categories": ["advertising"],
  "auto_freeze_at": null,
  "metadata": { "campaign": "spring_2026" },
  "created_at": "2026-04-15T12:00:00Z",
  "expires_at": "2029-04-15T23:59:59Z"
}

GET /cards Список всех карт с фильтрами и пагинацией

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

Параметр	Тип		Описание
status	string	optional	`active`, `frozen`, `terminated`
bin_id	string	optional	Фильтр по BIN
label	string	optional	Поиск по метке (частичное совпадение)
sort	string	optional	`created_at`, `balance`, `last_used`. По умолчанию: `created_at`
order	string	optional	`asc` или `desc`. По умолчанию: `desc`
page	integer	optional	Номер страницы. По умолчанию: `1`
per_page	integer	optional	Элементов на странице (1-100). По умолчанию: `25`

Ответ 200 OK

response.json

{
  "data": [
    {
      "id": "card_8xK2m9Lp4q",
      "bin_id": "491653",
      "network": "visa",
      "last4": "2039",
      "status": "active",
      "balance": 487.50,
      "label": "Meta Ads Campaign #12",
      "created_at": "2026-04-15T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 142,
    "total_pages": 6
  }
}

GET /cards/{card_id} Получить сводку карты (без конфиденциальных данных)

Возвращает информацию о карте без конфиденциальных данных. Используйте /cards/{card_id}/details для полного PAN и CVV.

Ответ 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "bin_id": "491653",
  "network": "visa",
  "last4": "2039",
  "status": "active",
  "balance": 487.50,
  "spending_limit": 2000.00,
  "total_spent": 12.50,
  "transaction_count": 3,
  "label": "Meta Ads Campaign #12",
  "metadata": { "campaign": "spring_2026" },
  "created_at": "2026-04-15T12:00:00Z",
  "expires_at": "2029-04-15T23:59:59Z",
  "last_used_at": "2026-04-15T14:32:00Z"
}

GET /cards/{card_id}/details Получить полный PAN, CVV и срок действия

Конфиденциальный эндпоинт

Возвращает полный PAN, CVV и срок действия. PCI-конфиденциально — никогда не логируйте и не храните в незашифрованном виде. Лимит: 30 зап/мин.

Ответ 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "pan": "4916531288472039",
  "cvv": "847",
  "exp_month": 4,
  "exp_year": 2029,
  "holder_name": "ANONYMOUS",
  "billing_address": {
    "line1": "123 Privacy Street",
    "city": "Wilmington",
    "state": "DE",
    "zip": "19801",
    "country": "US"
  }
}

PATCH /cards/{card_id} Обновить настройки карты

Тело запроса

Параметр	Тип		Описание
label	string	optional	Обновить метку карты
spending_limit	number	optional	Обновить месячный лимит расходов
allowed_categories	string[]	optional	Обновить разрешённые категории MCC
auto_freeze_at	number	optional	Установить порог автозаморозки. `0` для отключения.
metadata	object	optional	Объединить с существующими метаданными

Ответ 200 OK

Возвращает обновлённый объект карты.

POST /cards/{card_id}/freeze Временно приостановить карту

Приостанавливает все транзакции. Баланс сохраняется. Карту можно разморозить позже.

Ответ 200 OK

response.json

{ "id": "card_8xK2m9Lp4q", "status": "frozen", "frozen_at": "2026-04-15T15:00:00Z" }

POST /cards/{card_id}/unfreeze Разблокировать замороженную карту

Возобновляет транзакции на замороженной карте. Возвращает объект карты с status: "active".

DELETE /cards/{card_id} Навсегда закрыть карту

Необратимое действие

Закрытие карты необратимо. Остаток баланса мгновенно возвращается в кошелёк.

Ответ 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "status": "terminated",
  "refunded_amount": 487.50,
  "terminated_at": "2026-04-15T16:00:00Z"
}

Пополнение

Пополнение карт

Добавляйте или выводите средства с отдельных карт. Средства берутся из баланса кошелька.

POST /cards/{card_id}/fund Добавить средства на карту

Тело запроса

Параметр	Тип		Описание
amount	number	required	Сумма в USD для добавления. Мин: $1.00, Макс: $5,000.00

Ответ 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "previous_balance": 487.50,
  "funded_amount": 200.00,
  "new_balance": 687.50,
  "wallet_balance": 1312.50
}

POST /cards/{card_id}/withdraw Вывести средства обратно в кошелёк

Тело запроса

Параметр	Тип		Описание
amount	number	required	Сумма в USD для вывода с карты обратно в кошелёк

Ответ 200 OK

Возвращает обновлённые балансы карты и кошелька.

Транзакции

История транзакций

Просмотр всех транзакций по вашим картам. Включает авторизации, расчёты, возвраты и отказы.

GET /transactions Список всех транзакций с фильтрами

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

Параметр	Тип		Описание
card_id	string	optional	Фильтр по карте
type	string	optional	`authorization`, `settlement`, `refund`, `decline`
from	string	optional	Дата начала (ISO 8601)
to	string	optional	Дата окончания (ISO 8601)
merchant	string	optional	Поиск по имени продавца (частичное совпадение)
min_amount	number	optional	Минимальная сумма транзакции
max_amount	number	optional	Максимальная сумма транзакции
page	integer	optional	Номер страницы. По умолчанию: `1`
per_page	integer	optional	Элементов на странице (1-100). По умолчанию: `50`

Ответ 200 OK

response.json

{
  "data": [
    {
      "id": "txn_a1b2c3d4",
      "card_id": "card_8xK2m9Lp4q",
      "type": "settlement",
      "amount": -12.50,
      "currency": "USD",
      "merchant": {
        "name": "FACEBK ADS",
        "category": "advertising",
        "mcc": "7311",
        "country": "US"
      },
      "balance_after": 487.50,
      "created_at": "2026-04-15T14:32:00Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 50, "total": 328 }
}

GET /transactions/{txn_id} Получить полные детали транзакции

Возвращает полный объект транзакции, включая данные продавца, код MCC, статус 3DS и хронологию авторизации.

Кошелёк

Кошелёк & Депозиты

Управляйте кошельком аккаунта. Вносите крипто, проверяйте балансы и отслеживайте входящие депозиты.

GET /wallet/balance Получить баланс и статистику кошелька

Ответ 200 OK

response.json

{
  "balance": 1312.50,
  "currency": "USD",
  "pending_deposits": 500.00,
  "total_deposited": 15000.00,
  "total_spent": 13687.50,
  "cards_active": 8,
  "cards_total_balance": 2450.00
}

GET /wallet/deposit-address Получить адреса для крипто-депозитов

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

Параметр	Тип		Описание
currency	string	optional	`btc`, `eth`, `sol`, `usdt`. Пропустить для получения всех.

Ответ 200 OK

response.json

{
  "addresses": {
    "btc": "bc1qxy2kgdygjrsqtzq2n0yrf...",
    "eth": "0x742d35Cc6634C0532925a3b...",
    "sol": "7xKXtg2CW87d97TXJSDpbD5j...",
    "usdt": "0x742d35Cc6634C0532925a3b..."
  },
  "networks": {
    "btc": "bitcoin",
    "eth": "ethereum",
    "sol": "solana",
    "usdt": "erc-20"
  },
  "min_deposit": {
    "btc": "0.0001",
    "eth": "0.005",
    "sol": "0.1",
    "usdt": "5.00"
  }
}

GET /wallet/deposits Список истории депозитов

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

Параметр	Тип		Описание
status	string	optional	`pending`, `confirmed`, `expired`
currency	string	optional	Фильтр по криптовалюте

Ответ 200 OK

response.json

{
  "data": [
    {
      "id": "dep_x9y8z7w6",
      "currency": "btc",
      "amount_crypto": "0.0075",
      "amount_usd": 500.00,
      "fee_usd": 10.00,
      "credited_usd": 490.00,
      "status": "confirmed",
      "tx_hash": "3a1b2c3d4e5f...",
      "confirmations": 6,
      "created_at": "2026-04-15T10:00:00Z",
      "confirmed_at": "2026-04-15T10:42:00Z"
    }
  ]
}

BINs

Выбор BIN

Список доступных диапазонов BIN с их возможностями, лимитами и показателями приёма.

GET /bins Список всех доступных BIN

Ответ 200 OK

response.json

{
  "data": [
    {
      "id": "491653",
      "network": "visa",
      "type": "advertising",
      "issuer_country": "US",
      "3ds": true,
      "apple_pay": true,
      "google_pay": true,
      "max_transaction": 5000.00,
      "max_monthly": 50000.00,
      "acceptance_rate": 97.2,
      "best_for": ["meta_ads", "google_ads", "tiktok_ads"]
    },
    {
      "id": "531993",
      "network": "mastercard",
      "type": "everyday",
      "issuer_country": "US",
      "3ds": true,
      "apple_pay": true,
      "google_pay": true,
      "max_transaction": 1000.00,
      "max_monthly": 10000.00,
      "acceptance_rate": 95.8,
      "best_for": ["subscriptions", "saas", "shopping"]
    }
  ]
}

3D Secure

Аутентификация 3D Secure

Получайте вызовы 3DS и коды OTP. Все карты автоматически зарегистрированы в 3DS 2.0.

GET /3ds Список ожидающих вызовов 3DS

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

Параметр	Тип		Описание
card_id	string	optional	Фильтр по карте
status	string	optional	`pending`, `completed`, `expired`

Ответ 200 OK

response.json

{
  "data": [
    {
      "id": "3ds_m4n5o6p7",
      "card_id": "card_8xK2m9Lp4q",
      "merchant": "SPOTIFY",
      "amount": 9.99,
      "otp": "847291",
      "status": "pending",
      "expires_at": "2026-04-15T15:05:00Z",
      "created_at": "2026-04-15T15:00:00Z"
    }
  ]
}

GET /3ds/{challenge_id} Получить конкретный OTP 3DS

Возвращает полный объект вызова 3DS, включая код OTP. OTP истекают через 5 минут.

Webhooks

Webhooks & События

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

Доступные события

card.createdНовая карта выпущена

card.frozenКарта заморожена

card.unfrozenКарта разморожена

card.terminatedКарта закрыта

card.fundedСредства добавлены на карту

transaction.authorizedТранзакция авторизована

transaction.settledТранзакция проведена

transaction.declinedТранзакция отклонена

transaction.refundedВозврат обработан

3ds.challengeТребуется верификация 3DS

deposit.pendingКрипто-депозит обнаружен

deposit.confirmedКрипто-депозит подтверждён

Проверка подписи

verify-webhook.py

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

POST /webhooks Зарегистрировать endpoint webhook

Тело запроса

Параметр	Тип		Описание
url	string	required	URL HTTPS-эндпоинта для приёма событий
events	string[]	required	Типы событий для подписки. Используйте `["*"]` для всех.
secret	string	optional	Пользовательский секрет подписи. Генерируется автоматически при пропуске.

Ответ 201 Created

response.json

{
  "id": "wh_r5s6t7u8",
  "url": "https://yourapp.com/webhooks/ctc",
  "events": ["transaction.authorized", "transaction.declined"],
  "secret": "whsec_a1b2c3d4e5f6...",
  "active": true,
  "created_at": "2026-04-15T12:00:00Z"
}

GET /webhooks Список зарегистрированных webhooks

Возвращает массив всех зарегистрированных endpoint-ов webhook с их подписками на события и статусом.

DELETE /webhooks/{webhook_id} Удалить webhook

Безвозвратно удаляет webhook. На этот endpoint больше не будут доставляться события.

SDKs

SDKs & Библиотеки

Официальные клиентские библиотеки для вашего стека. Все SDK поддерживают рабочую и sandbox среды.

Python

pip install cryptotopcard

Node.js

npm i cryptotopcard

Go

go get cryptotopcard

Быстрый старт — Python

quickstart.py

from cryptotopcard import Client

client = Client("sk_live_your_api_key")

# Создать карту
card = client.cards.create(
    bin_id="491653",
    amount=500,
    label="Ad Spend"
)
print(card.id, card.last4)

# Получить полные данные карты (PAN, CVV)
details = client.cards.details(card.id)
print(details.pan, details.cvv)

# Пополнить карту
client.cards.fund(card.id, amount=200)

# Список транзакций
txns = client.transactions.list(card_id=card.id)
for t in txns.data:
    print(t.merchant.name, t.amount)

Быстрый старт — Node.js

quickstart.js

const { CryptoTopCard } = require('cryptotopcard');

const client = new CryptoTopCard('sk_live_your_api_key');

// Создать карту
const card = await client.cards.create({
  binId: '491653',
  amount: 500,
  label: 'Ad Spend',
});

// Получить OTP 3DS
const challenges = await client.threeds.list({
  cardId: card.id,
  status: 'pending',
});

// Настроить webhooks
await client.webhooks.create({
  url: 'https://yourapp.com/hooks',
  events: ['transaction.authorized', '3ds.challenge'],
});

API Справочник

API-ключи & Аутентификация

Безопасность API-ключа

Управление картами

Конфиденциальный эндпоинт

Необратимое действие

Пополнение карт

История транзакций

Кошелёк & Депозиты

Выбор BIN

Аутентификация 3D Secure

Webhooks & События

SDKs & Библиотеки

Python

Node.js

Go

С возвращением

Создание аккаунта

Аккаунт создан