Virtual Cards

Виртуальные карты as-a-Service на ваших managed customers: выпуск (issue), список, детали и пополнение (top-up). Каждая карта привязана к конкретному customer'у и номинирована в RUB. Наружу отдаётся только обезличенное представление карты — внутренний платёжный контур не раскрывается.

⚠

Денежные операции дормант

Выпуск и пополнение карт в live по умолчанию выключены и возвращают 503, пока функция не активирована для платформы. В sandbox всё работает на синтетике: POST /cards отдаёт фиктивную карту с искусственным masked_pan, а POST /cards/{card}/topup симулирует зачисление, не обращаясь к апстриму.

ℹ

Окружение по префиксу ключа

Как и во всём B2B API, окружение выводится из префикса ключа: sk_test_ = sandbox, sk_live_ = live. Отдельного заголовка нет. Карта видна только тому ключу, чьё окружение совпадает с env карты; обращение к карте из чужого окружения возвращает 404 (намеренно, чтобы не раскрывать существование).

Объект карты

Все endpoints возвращают карту в одном и том же обезличенном виде:

Card object

Name	Type	Required	Description
`id`	`string`	optional	UUID карты. Используется в путях `/cards/{card}`.
`status`	`string`	optional	Статус карты в нижнем регистре, напр. `open`.
`masked_pan`	`string\|null`	optional	Маскированный номer, напр. `537643••••9f3a`. Для только что выпущенной live-карты может быть `null`, пока не подтянется снимок при `GET /cards/{card}`.
`balance`	`string`	optional	Баланс в RUB строкой с 2 знаками, напр. `0.00`.
`currency`	`string`	optional	Всегда `RUB`.
`created_at`	`string`	optional	ISO 8601 timestamp создания.
`markup`	`object`	optional	Ваша наценка (%) по операциям карт: `issue_pct`, `topup_pct`, `payout_pct`. `0`, если наценка не настроена.

Выпуск карты

POST /api/v1/customers/{uuid}/cards

⚷ Bearer Token

Выпустить виртуальную карту для customer'а

Все поля профиля держателя необязательны — карту можно выпустить и без них. В sandbox возвращается детерминированная синтетическая карта; в live операция дормант (см. предупреждение выше).

Body

Name	Type	Required	Description
`first_name`	`string`	optional	Имя держателя. До 100 символов.
`last_name`	`string`	optional	Фамилия держателя. До 100 символов.
`patronymic`	`string`	optional	Отчество. До 100 символов.
`birth_date`	`string`	optional	Дата рождения. До 20 символов.
`email`	`string`	optional	Email держателя. Валидный email, до 150 символов.

Responses

{
  "data": {
    "id": "1a7ee75b-7f0e-48af-a075-a56721f1140e",
    "status": "open",
    "masked_pan": "537643••••9f3a",
    "balance": "0.00",
    "currency": "RUB",
    "created_at": "2026-07-13T12:41:08+00:00",
    "markup": {
      "issue_pct": 2.5,
      "topup_pct": 1.5,
      "payout_pct": 1.0
    }
  }
}

Список карт

GET /api/v1/customers/{uuid}/cards

⚷ Bearer Token

Все карты customer'а

Возвращает карты данного customer'а в текущем окружении, самые свежие первыми.

Responses

{
  "data": [
    {
      "id": "1a7ee75b-7f0e-48af-a075-a56721f1140e",
      "status": "open",
      "masked_pan": "537643••••9f3a",
      "balance": "1500.00",
      "currency": "RUB",
      "created_at": "2026-07-13T12:41:08+00:00",
      "markup": {
        "issue_pct": 2.5,
        "topup_pct": 1.5,
        "payout_pct": 1.0
      }
    }
  ]
}

Детали карты

GET /api/v1/customers/{uuid}/cards/{card}

⚷ Bearer Token

Одна карта по UUID

В live (если функция включена) подтягивает свежий снимок баланса/статуса; иначе отдаёт последний локальный снимок. При любой ошибке апстрима наружу возвращается локальный снимок — сырой ответ провайдера не раскрывается.

Responses

{
  "data": {
    "id": "1a7ee75b-7f0e-48af-a075-a56721f1140e",
    "status": "open",
    "masked_pan": "537643••••9f3a",
    "balance": "1500.00",
    "currency": "RUB",
    "created_at": "2026-07-13T12:41:08+00:00",
    "markup": {
      "issue_pct": 2.5,
      "topup_pct": 1.5,
      "payout_pct": 1.0
    }
  }
}

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

POST /api/v1/customers/{uuid}/cards/{card}/topup

⚷ Bearer Token

Пополнить карту со счёта площадки (RUB)

Зачисляет RUB на карту. В sandbox зачисление симулируется и баланс сразу увеличивается; в live операция дормант (503, пока функция не активирована). Ответ приходит с кодом 202 Accepted — карта пополняется асинхронно.

Body

Name	Type	Required	Description
`amount`	`string`	required	Сумма пополнения в RUB. Строка-число до 2 знаков после точки, напр. `1500.00` или `1500`.

Responses

{
  "data": {
    "status": "accepted",
    "amount": "1500.00",
    "currency": "RUB",
    "card_id": "1a7ee75b-7f0e-48af-a075-a56721f1140e",
    "pricing": {
      "markup_pct": 1.5
    },
    "sandbox": true
  }
}

pricing.markup_pct — ваша наценка на пополнение (та же, что markup.topup_pct в объекте карты). Флаг sandbox присутствует только в sandbox-ответах; в live его нет.

Коды ошибок

Ошибки приходят в стандартном конверте { "error": { "code", "message", "request_id" } }. Успех — { "data": ... }.

Introduction.'], ]" />