API выпуска виртуальных карт

Выпускайте, пополняйте и закрывайте виртуальные карты Visa и Mastercard в USD из своей системы.

Через API ваша система регистрирует держателей, выпускает карты, пополняет их, читает выписку, получает коды подтверждения и закрывает карты с возвратом остатка. Расчёты идут с вашего предоплаченного баланса в USD.

Базовый URL

https://api.plativputi.com/api/partner/v1

Все запросы — HTTPS, тела — JSON в UTF-8. Каждый запрос подписывается HMAC-SHA256 ключом вашего аккаунта, см. Аутентификация и подпись.

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

Проверить ключ и подпись проще всего на балансе:

TS=$(date +%s)
SIG=$(printf '%s\n%s\n%s\n%s' "$TS" "GET" "/api/partner/v1/balance" "" \
  | openssl dgst -sha256 -hmac "$PP_SECRET" -hex | awk '{print $NF}')

curl -sS "https://api.plativputi.com/api/partner/v1/balance" \
  -H "X-Key-Id: $PP_KEY_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

{ "currency": "USD", "balance": "1250.5", "hold": "0", "available": "1250.5" }

Как устроена интеграция

Получите ключ у вашего менеджера: идентификатор pp_live_… и секрет. Для отладки есть тестовый аккаунт с ключом pp_test_….
Выберите тариф — GET /tariffs. В тарифе цена выпуска, комиссии пополнения и закрытия, лимиты суммы.
Зарегистрируйте держателя — POST /cardholders с вашим external_id, именем и почтой.
Выпустите карту — POST /cards. Ответ 202: операция принята, карта появится через несколько секунд. Результат придёт событием card.issued.
Обслуживайте карту — пополнение POST /cards/{id}/topup, баланс GET /cards/{id}, выписка, коды 3-D Secure, закрытие.

Пошагово с примерами — в Быстром старте.

Главные свойства API

Свойство	Что это значит для вас
Асинхронные операции	Выпуск и пополнение отвечают `202` с операцией. Итог — событием или через `GET /operations/{id}`.
Резерв, а не списание	Сумма операции резервируется на балансе и списывается только при успехе. При неудаче резерв снимается целиком.
Идемпотентность	Денежные `POST` требуют `Idempotency-Key`. Повтор с тем же ключом никогда не создаст вторую карту или второе пополнение.
Доставка событий at-least-once	События лежат в очереди, пока вы их не подтвердите. Плюс вебхуки с той же подписью, что и запросы.
Деньги — строки	Суммы — десятичные строки в USD (`"57.0464"`). Не парсите их во `float`.

Разделы справочника

Раздел	Что делает
Аккаунт	Баланс, тарифы, расчёт стоимости
Держатели	Регистрация и поиск держателей
Карты	Выпуск, пополнение, закрытие, выписка, коды, реквизиты
Операции	Статус асинхронной операции
События	Очередь событий и подтверждение
Вебхуки	Подписки на push-доставку событий

Машиночитаемая спецификация OpenAPI 3.1: openapi.json. Её можно импортировать в Postman или сгенерировать по ней типы.