Инфраструктура выпуска карт
API виртуальных карт — выпускайте карты Visa и Mastercard своим клиентам.
ScarabPay Business выпускает виртуальные карты вашим клиентам с финансированием из пополняемого кошелька мерчанта. Каждое движение записывается сбалансированными проводками двойной записи в журнал, куда можно только добавлять, поэтому ваши отчётные цифры и наши записи — одни и те же записи.
// Idempotency-Key: 8f3c1d90-...-b7a2
{
"product_id": "01HXYZP4K2M8N6Q1RSTVWXYZ01",
"customer_id": "01HABCD7F3G9J5K2LMNPQRSTVW",
"amount_minor": 250000
}Ledger · insert only
01
Путь денег
Как работает API виртуальных карт.
Сначала — пополнение, иначе нельзя: запрос на выпуск при пустом кошельке отклоняется, а не ставится в очередь. Ниже нет «этапов» из маркетинговой схемы — каждый шаг это эндпоинт, который вы вызываете, или событие, которое вы получаете.
-
Пополните кошелёк
Кошелёк мерчанта хранит отдельный баланс для каждой валюты в целых минорных единицах. Криптопополнения приходят на постоянные адреса для каждой сети и зачисляются после подтверждения сетью.
POST /deposit-addresses
-
Выпустите карту клиенту
Один POST содержит продукт, клиента из реестра и первоначальное пополнение. Сумма пополнения и комиссия за выпуск резервируются в кошельке, партнёр-эмитент вызывается вне транзакции базы данных, а расчёт записывает движение в журнал. Для карт с асинхронным выпуском возвращается 202 и карта в статусе pending.
POST /cards
-
Получайте активность в реальном времени
Авторизации и изменения жизненного цикла приходят к вам подписанными вебхуками — выпуск, авторизация, пополнение, заморозка, разморозка, закрытие. Ту же активность можно читать по каждой карте с курсорной пагинацией.
GET /cards/{card}/transactions
-
Сверяйтесь по записям, а не по итогам
Сверка — это чтение журнала. Ничего не обновляется и не удаляется, поэтому цифра из отчёта за прошлый квартал по-прежнему сводится к записям, из которых она получена.
GET /deposits
02
Партнёры-эмитенты
Один API выпуска виртуальных карт перед несколькими эмитентами.
Вы интегрируетесь один раз. За этой интеграцией каждый карточный продукт направляется к лицензированному партнёру-эмитенту, выбранному по региону и набору продуктов. Добавление или замена партнёра — это наша миграция, а не ваша: ваш запрос не меняется.
Имена партнёров не публикуются и не раскрываются ни через API, ни в каком-либо ответе.
03
Разработчикам
Интеграция API виртуальных карт, рассчитанная на повторы.
О финансовом API судят по тому, что происходит при второй попытке. Каждый изменяющий эндпоинт требует Idempotency-Key, тот же ключ передаётся эмитенту как клиентский референс, а повтор возвращает исходный результат, а не второе движение средств.
{
"data": {
"id": "01HKQW2N8V4X6Z9B3D5F7HJKMN",
"status": "active",
"masked_number": "••••••••••••4417",
"balance_minor": 250000,
"currency": "USD"
}
}Delivered to your endpoint
Every delivery carries a timestamped HMAC signature you verify with your endpoint secret.
REST и JSON, единый формат ответа
Предсказуемые ответы об успехе, обработке и ошибке. Публичные идентификаторы — ULID; внутренние автоинкрементные id никогда не покидают систему.
Идемпотентность обязательна
Изменяющий запрос без Idempotency-Key отклоняется. Повторное использование ключа с другими данными тоже отклоняется, а не принимается молча.
Подписанные вебхуки с повторами
События по картам и пополнениям доставляются с HMAC-подписью метки времени и тела и повторяются при сбое.
Целые минорные единицы на всём пути
В денежном потоке нет ни одного числа с плавающей точкой — ни в запросе, ни в ответе, ни в строке журнала.
04
Что есть уже сейчас
Возможности API виртуальных карт: четырнадцать операций, без обещаний.
Четырнадцать задокументированных операций на одиннадцати путях: выпуск карт, реестр держателей и пополнение. Всего, что не указано в этом списке, вызвать нельзя.
| Cards | |
|---|---|
| POST /cards | Issues a card against a product, to a registry customer, with an initial load. Charges the load plus the product issue fee through hold → provider → settle. Returns 202 with a pending card when the issuer provisions asynchronously. |
| GET /cards/{card} | Returns the card's current state. Poll it while a new card provisions — pending resolves to active. |
| POST /cards/{card}/recharge | Loads more funds onto a live card from the wallet, as a new balanced movement. |
| POST /cards/{card}/freeze | Blocks spend on a card without moving money. Reversed by /unfreeze. |
| POST /cards/{card}/terminate | Ends a card permanently and returns its residual balance to the wallet. |
| GET /cards/{card}/transactions | Provider-reported activity for one card, cursor-paginated. |
| Cardholders | |
| POST /customers | Registers a cardholder identity once. Stored encrypted at rest and submitted to the issuer inside an issue request. |
| GET /customers/{customer} | Reads a registry customer. PAN and security code are never exposed and never persisted. |
| Funding | |
| POST /deposit-addresses | Creates a permanent per-network address that credits the merchant wallet on receipt. |
| GET /deposits | Received deposits, reconciled against the ledger. |
Unfreeze, list customers, update a customer and list deposit addresses complete the fourteen.
Каждое движение сводится к проводкам с нулевой суммой.
Авторизация не меняет баланс напрямую. Она резервирует средства в кошельке мерчанта, вызывает эмитента вне транзакции базы данных и записывает движение равными противоположными проводками в журнал, куда можно только добавлять. Исправления записываются новыми проводками, а не правками.
Журнал — источник истины для каждой цифры, которую показывает платформа, включая цифры в кабинете самого мерчанта.
Card number ending 4417
- Cardholder
- A. HADDAD
- Expires
- 04/29
Ledger excerpt · demonstration data
05
Как это используют
Виртуальные карты для финтеха и бизнеса.
В этом API нет поля лимита, правил по категориям мерчантов и переключателя каналов, и строить решение вокруг них — значит строить вокруг того, чего нет. Вы управляете тем, сколько денег на карте: задаёте при выпуске, меняете пополнением, возвращаете при закрытии. Из этого вытекают три сценария.
01
Карта для каждого клиента
У вашей платформы один кошелёк; у каждого конечного клиента — карта, пополненная из него. Риск по клиенту равен загруженному балансу, а его данные — запись в реестре держателей, а не повторно отправляемые данные.
02
Выплаты картами
Платите продавцу или подрядчику, выпуская карту на причитающуюся сумму. Добавляйте пополнением и закрывайте по окончании работы — остаток вернётся в кошелёк сбалансированным движением.
03
Карта на каждого поставщика
Выпускайте отдельную карту на каждого поставщика или подписку и пополняйте её на сумму этих отношений. Расходы сверх пополнения не авторизуются, а активность каждой карты видна отдельно.
Частые вопросы
Что такое API виртуальных карт?
Это REST API, через который ваша платформа выпускает виртуальные карты Visa и Mastercard своим клиентам, пополняет их и управляет ими — заморозка, разморозка, пополнение и закрытие — без собственной инфраструктуры выпуска карт.
Как пополняются карты?
У каждого мерчанта есть USD-кошелёк. Он пополняется стейблкоинами на постоянные адреса для каждой сети и зачисляется после подтверждения сетью. Первоначальное пополнение карты и комиссия за выпуск списываются из этого кошелька.
Как ограничить расходы по карте?
Через её баланс. Вы задаёте сумму при выпуске, увеличиваете её пополнением, блокируете расходы заморозкой и закрываете карту, чтобы вернуть остаток в кошелёк.
Как узнать, что происходит с картой?
События по картам и пополнениям приходят на ваш эндпоинт вебхуками с подписью HMAC-SHA256 и повторяются при сбое. Ту же активность можно читать по каждой карте через API.
ScarabPay — это банк?
Нет. Мы не банк и не имеем банковской лицензии. Карты выпускаются через лицензированных партнёров-эмитентов.
Как начать?
Свяжитесь с нами, чтобы запросить доступ. Перед боевой работой ваш бизнес проходит верификацию, а тестовые API-ключи позволяют интегрироваться на игровых деньгах уже сейчас.
Каждое утверждение на этой странице сводится к операции.
Посмотрите, что умеет API, или напишите нам, что вы строите, — мы прямо скажем, подходит ли это.