API для выпуска и управления картами

CardOS — REST API: выпуск виртуальных карт, пополнение, транзакции, выписки, лимиты, кэшбэк, реквизиты и KYC. Мульти-тенант, money-safe, идемпотентность и подписанные вебхуки из коробки.

База: https://cardos.dev/api/v1 Bearer-ключи (test / live) Idempotency на деньгах HMAC-вебхуки

Полный справочник API → OpenAPI (YAML) Получить ключ

Два способа подключиться

🧩 Конструктор без кода

Собрать готового card-бота за 5 шагов в кабинете: бренд, бот, стиль, наценка → запуск. Подходит большинству — код не нужен.

Открыть конструктор

⚙️ API-интеграция для разработчиков

Встроить выпуск/управление картами в свой продукт по REST API. Полный контроль над флоу. Гайд ниже.

К гайду интеграции

Быстрый старт

1. Получите API-ключ в кабинете /partner/developers (раздел «Разработчикам»). Ключ cms_sk_test_… — sandbox без реальных денег.

2. Первый вызов — баланс конечного пользователя:

curl "https://cardos.dev/api/v1/balance?external_user_ref=<tg_id>" \
  -H "Authorization: Bearer cms_sk_test_…"

3. Выпуск карты (денежная операция → заголовок Idempotency-Key):

curl -X POST "https://cardos.dev/api/v1/cards" \
  -H "Authorization: Bearer cms_sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_user_ref":"123456","product":"VIRT-USD-NOKYC"}'

💡 test — sandbox (стаб-движок, безопасно экспериментировать). live — боевой режим, включается отдельно по согласованию.

Авторизация

Каждый запрос — заголовок Authorization: Bearer <ключ>. Ключи привязаны к проекту (тенанту) и режиму (test/live); данные строго изолированы по тенанту. Ключ хранится у нас только хэшем — секрет показывается один раз при выпуске.

Идемпотентность

Денежные операции (POST /cards, POST /deposits) требуют заголовок Idempotency-Key — повтор с тем же ключом не создаёт дубль.

Основные эндпоинты

Метод	Путь	Назначение
GET	`/balance`	Баланс конечника
POST	`/cards`	Выпуск карты
GET	`/cards/{id}`	Детали (маскированные)
POST	`/cards/{id}/freeze · /unfreeze · /kill · /set-pin`	Управление картой
POST	`/cards/{id}/controls`	Лимиты трат (авто-заморозка)
POST	`/cards/{id}/reveal · /session`	Hosted показ реквизитов / экраны
GET	`/cards/{id}/transactions`	Транзакции (FX, комиссия, MCC)
POST	`/deposits`	Пополнение баланса
GET	`/statements · /analytics/spending`	Выписка (CSV) · аналитика
GET	`/products · /products/rates`	Каталог продуктов · тарифы
POST	`/kyc` · `/disputes`	KYC hosted-флоу · диспуты

→ Полный справочник со схемами запросов/ответов

Пошаговый гайд: от входа до боевого

1. Вход и проект

Войдите в кабинет через Telegram → создайте проект в «Конструкторе» (бренд, бот от @BotFather, наценка). Затем «Разработчикам» → «+ Ключ sandbox» — секрет показывается один раз.

2. Подготовьте баланс конечника

# создать депозит
curl -X POST https://cardos.dev/api/v1/deposits \
  -H "Authorization: Bearer cms_sk_test_…" -H "Idempotency-Key: dep-001" \
  -H "Content-Type: application/json" \
  -d '{"external_user_ref":"123456","amount":"100","method":"usdt_trc20"}'

# подтвердить (ТОЛЬКО sandbox; в live — on-chain watcher)
curl -X POST https://cardos.dev/api/v1/sandbox/deposits/<deposit_id>/confirm \
  -H "Authorization: Bearer cms_sk_test_…"

3. Выпустите карту и проверьте

# продукты → выберите productCode
curl https://cardos.dev/api/v1/products -H "Authorization: Bearer cms_sk_test_…"

# выпуск карты
curl -X POST https://cardos.dev/api/v1/cards \
  -H "Authorization: Bearer cms_sk_test_…" -H "Idempotency-Key: iss-001" \
  -H "Content-Type: application/json" \
  -d '{"external_user_ref":"123456","product":"VIRT-USD-NOKYC"}'

# сэмулировать трату (sandbox) и посмотреть транзакции
curl -X POST https://cardos.dev/api/v1/sandbox/cards/<card_id>/transactions \
  -H "Authorization: Bearer cms_sk_test_…" -H "Content-Type: application/json" \
  -d '{"type":"expense","amount":"25.50","merchant":"Starbucks","mcc":"5814"}'
curl "https://cardos.dev/api/v1/cards/<card_id>/transactions" -H "Authorization: Bearer cms_sk_test_…"

4. Покажите карту пользователю (hosted-экраны)

POST /cards/{id}/session вернёт manage_url и transactions_url — откройте в webview конечнику (управление, реквизиты, выписка). Данные и PCI — на нашей стороне, не на вашей.

5. Вебхуки

Подпишитесь на события (см. раздел ниже) — transaction, balance, issued, card_status. Проверяйте подпись.

6. Боевой режим

Когда sandbox-флоу отлажен — пишите нам: включим live (реальные карты/деньги) по согласованию. Ключи и код не меняются — только режим.

FAQ

Чем отличается test от live?

cms_sk_test_… — sandbox: всё на заглушке, реальные деньги не двигаются. cms_sk_live_… — боевой, включается отдельно.

Зачем Idempotency-Key?

На денежных операциях (выпуск, депозит) — чтобы повтор запроса (ретрай, обрыв сети) не создал дубль. Любой уникальный ключ на операцию.

Кто держит средства?

CardOS (Merchant of Record). Вы не касаетесь денег конечников — только наценка как ваш доход.

Виден ли партнёру провайдер карт / PII пользователей?

Нет. Провайдер скрыт (наружу — «CardOS»), данные тенантов изолированы, PII конечников вам не отдаём.

Нужен ли KYC?

Зависит от продукта карты (поле kyc_required в /products). Для KYC-продуктов — hosted-флоу POST /kyc.

Вебхуки

CardOS шлёт исходящие вебхуки на ваш endpoint (события: transaction, balance, issued, card_status, kyc). Каждый запрос подписан:

X-CardOS-Signature: t=<unix>,v1=<hex>

v1 = HMAC_SHA256(secret, "<t>.<raw_body>")

Проверьте подпись и сравните t с текущим временем (анти-replay). Endpoint регистрируется через POST /webhook-endpoints; секрет возвращается один раз.