PlatinaКабинет партнёра

API v1

Документация API

Выпуск и пополнение карт Visa и Mastercard, операции по картам, приём платежей по СБП и вебхуки.

Начало работы

Все запросы идут по HTTPS на один адрес. Тело запроса и ответ — JSON в UTF-8. Суммы передаются строками с двумя знаками после точки, время — в ISO 8601, UTC.

Адрес API

https://api.platina.info/v1
  1. Подайте заявку в боте и выберите тариф API.
  2. После подключения вы получаете ключи и секрет для вебхуков.
  3. Пополните баланс в USDT, выпустите карту и пополните её.

API карт

$3 000 единоразово за подключение. Депозит на выпуск карт вносится отдельно в кабинете после оплаты подключения: от 1 000 карт × $1,50, меньший объём — индивидуально.

API карт и СБП

$5 900 единоразово за подключение. Депозит на выпуск карт вносится отдельно в кабинете после оплаты подключения: от 1 000 карт × $1,50, меньший объём — индивидуально.

Подать заявку в боте

Авторизация

Передавайте секретный ключ в заголовке Authorization. Тестовый ключ начинается с sk_test_, боевой — с sk_live_. В тестовом режиме карты и платежи не настоящие, деньги не списываются.

Authorization: Bearer sk_live_...

Ключ используется только на вашем сервере. Не передавайте его в браузер и мобильное приложение. Если ключ мог попасть к посторонним, запросите перевыпуск в боте.

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

Для запросов POST, которые двигают деньги или выпускают карту, передавайте заголовок Idempotency-Key с уникальным значением, например UUID. Повторный запрос с тем же ключом в течение 24 часов вернёт первый ответ и не выполнит действие второй раз. Это защищает от двойного пополнения при обрыве соединения.

Баланс

С баланса партнёра списываются пополнения карт. Баланс ведётся в USD и пополняется в USDT. Оплаченные карты из пакета списываются по одной при выпуске.

Получить баланс

GET/balance

Доступные средства и остаток оплаченных карт.

Запрос

curl -X GET https://api.platina.info/v1/balance \
  -H "Authorization: Bearer sk_live_..."

Ответ

{
  "available": "12500.00",
  "currency": "USD",
  "cards_remaining": 640
}

Адрес для пополнения баланса

GET/balance/deposit-address

Постоянный адрес для перевода USDT. После зачисления приходит вебхук balance.deposited.

Параметры
networkstring · обязательныйСеть: TRC20 или TON

Запрос

curl -X GET https://api.platina.info/v1/balance/deposit-address?network=TRC20 \
  -H "Authorization: Bearer sk_live_..."

Ответ

{
  "asset": "USDT",
  "network": "TRC20",
  "address": "TXk3...9QpL"
}

Карты

Виртуальные карты Visa и Mastercard в USD и EUR. Карта выпускается с нулевым балансом, пополняется с баланса партнёра.

Выпустить карту

POST/cards

Списывает одну карту из оплаченного пакета. Если передан topup, сумма сразу переводится с баланса партнёра на карту.

Параметры
networkstring · обязательныйvisa или mastercard
currencystring · обязательныйUSD или EUR
external_idstringВаш идентификатор клиента или заказа, до 64 символов
topupstringСумма первого пополнения в валюте карты, например "50.00"

Запрос

curl -X POST https://api.platina.info/v1/cards \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 7c1f0e52-3a9b-4d1e-9a55-0b6f2f1c8d10" \
  -H "Content-Type: application/json" \
  -d '{"network":"visa","currency":"USD","external_id":"user-1042"}'

Ответ

{
  "id": "card_9f2c1e7a",
  "status": "active",
  "network": "visa",
  "currency": "USD",
  "last4": "4421",
  "balance": "0.00",
  "external_id": "user-1042",
  "created_at": "2026-11-12T10:15:00Z"
}

Список карт

GET/cards

Карты от новых к старым, постранично.

Параметры
statusstringactive, frozen или closed
external_idstringФильтр по вашему идентификатору
limitintegerОт 1 до 100, по умолчанию 20
cursorstringЗначение next_cursor из предыдущего ответа

Запрос

curl -X GET https://api.platina.info/v1/cards?status=active&limit=20 \
  -H "Authorization: Bearer sk_live_..."

Ответ

{
  "data": [
    {
      "id": "card_9f2c1e7a",
      "status": "active",
      "network": "visa",
      "currency": "USD",
      "last4": "4421",
      "balance": "0.00",
      "external_id": "user-1042",
      "created_at": "2026-11-12T10:15:00Z"
    }
  ],
  "next_cursor": "c_eyJpZCI6ImNhcmRfOWYyYzFlN2EifQ"
}

Получить карту

GET/cards/{id}

Статус и текущий баланс карты.

Запрос

curl -X GET https://api.platina.info/v1/cards/card_9f2c1e7a \
  -H "Authorization: Bearer sk_live_..."

Ответ

{
  "id": "card_9f2c1e7a",
  "status": "active",
  "network": "visa",
  "currency": "USD",
  "last4": "4421",
  "balance": "50.00",
  "external_id": "user-1042",
  "created_at": "2026-11-12T10:15:00Z"
}

Реквизиты карты

GET/cards/{id}/details

Полный номер, срок и CVV. Запрашивайте только со своего сервера в момент показа клиенту. Не сохраняйте и не пишите реквизиты в логи.

Запрос

curl -X GET https://api.platina.info/v1/cards/card_9f2c1e7a/details \
  -H "Authorization: Bearer sk_live_..."

Ответ

{
  "number": "4000000000004421",
  "exp_month": 10,
  "exp_year": 2031,
  "cvv": "304",
  "holder": "IVAN PETROV"
}

Пополнить карту

POST/cards/{id}/topup

Переводит сумму с баланса партнёра на карту. Валюта — валюта карты.

Параметры
amountstring · обязательныйСумма, например "100.00"

Запрос

curl -X POST https://api.platina.info/v1/cards/card_9f2c1e7a/topup \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 7c1f0e52-3a9b-4d1e-9a55-0b6f2f1c8d10" \
  -H "Content-Type: application/json" \
  -d '{"amount":"100.00"}'

Ответ

{
  "id": "top_51b7c0d2",
  "card_id": "card_9f2c1e7a",
  "amount": "100.00",
  "currency": "USD",
  "status": "completed",
  "card_balance": "150.00",
  "created_at": "2026-11-12T10:20:11Z"
}

Вернуть средства с карты

POST/cards/{id}/withdraw

Переводит сумму с карты обратно на баланс партнёра.

Параметры
amountstring · обязательныйСумма не больше баланса карты

Запрос

curl -X POST https://api.platina.info/v1/cards/card_9f2c1e7a/withdraw \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 7c1f0e52-3a9b-4d1e-9a55-0b6f2f1c8d10" \
  -H "Content-Type: application/json" \
  -d '{"amount":"25.00"}'

Ответ

{
  "id": "wd_2e80a4f1",
  "card_id": "card_9f2c1e7a",
  "amount": "25.00",
  "currency": "USD",
  "status": "completed",
  "card_balance": "125.00",
  "created_at": "2026-11-12T10:31:40Z"
}

Заморозить и разморозить

POST/cards/{id}/freeze

Замороженная карта отклоняет оплаты, баланс сохраняется. Обратное действие — POST /cards/{id}/unfreeze.

Запрос

curl -X POST https://api.platina.info/v1/cards/card_9f2c1e7a/freeze \
  -H "Authorization: Bearer sk_live_..."

Ответ

{
  "id": "card_9f2c1e7a",
  "status": "frozen",
  "network": "visa",
  "currency": "USD",
  "last4": "4421",
  "balance": "125.00",
  "external_id": "user-1042",
  "created_at": "2026-11-12T10:15:00Z"
}

Закрыть карту

POST/cards/{id}/close

Действие необратимо. Остаток карты возвращается на баланс партнёра.

Запрос

curl -X POST https://api.platina.info/v1/cards/card_9f2c1e7a/close \
  -H "Authorization: Bearer sk_live_..."

Ответ

{
  "id": "card_9f2c1e7a",
  "status": "closed",
  "network": "visa",
  "currency": "USD",
  "last4": "4421",
  "balance": "0.00",
  "external_id": "user-1042",
  "created_at": "2026-11-12T10:15:00Z"
}

Операции

Покупки, возвраты, пополнения и списания по карте.

Операции по карте

GET/cards/{id}/transactions

От новых к старым. Сумма со знаком: списания отрицательные.

Параметры
from, tostringПериод в формате ISO 8601
limitintegerОт 1 до 100, по умолчанию 20
cursorstringЗначение next_cursor из предыдущего ответа

Запрос

curl -X GET https://api.platina.info/v1/cards/card_9f2c1e7a/transactions?limit=20 \
  -H "Authorization: Bearer sk_live_..."

Ответ

{
  "data": [
    {
      "id": "txn_a41c93e0",
      "card_id": "card_9f2c1e7a",
      "type": "purchase",
      "status": "settled",
      "amount": "-20.00",
      "currency": "USD",
      "merchant": { "name": "OPENAI", "mcc": "5734", "country": "US" },
      "created_at": "2026-11-12T09:30:02Z"
    }
  ],
  "next_cursor": null
}

Приём СБП

Тариф «API карт и СБП»

Счёт в рублях с оплатой по ссылке или QR-коду. После оплаты сумма за вычетом комиссии 1% зачисляется на баланс партнёра в USD по курсу на момент создания счёта.

Создать счёт

POST/sbp/invoices

Возвращает ссылку на оплату и QR-код. Покажите их клиенту в своём интерфейсе.

Параметры
amount_rubstring · обязательныйСумма счёта в рублях, например "10000.00"
external_idstringВаш идентификатор заказа
descriptionstringНазначение платежа, до 140 символов
expires_inintegerСрок жизни счёта в секундах, по умолчанию 900

Запрос

curl -X POST https://api.platina.info/v1/sbp/invoices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 7c1f0e52-3a9b-4d1e-9a55-0b6f2f1c8d10" \
  -H "Content-Type: application/json" \
  -d '{"amount_rub":"10000.00","external_id":"order-7731"}'

Ответ

{
  "id": "inv_6d02b9c4",
  "status": "pending",
  "amount_rub": "10000.00",
  "rate": "88.70",
  "payment_url": "https://pay.platina.info/i/inv_6d02b9c4",
  "qr_url": "https://pay.platina.info/i/inv_6d02b9c4/qr.png",
  "external_id": "order-7731",
  "expires_at": "2026-11-12T10:45:00Z"
}

Статус счёта

GET/sbp/invoices/{id}

Статусы: pending — ждёт оплаты, paid — оплачен, expired — истёк, canceled — отменён.

Запрос

curl -X GET https://api.platina.info/v1/sbp/invoices/inv_6d02b9c4 \
  -H "Authorization: Bearer sk_live_..."

Ответ

{
  "id": "inv_6d02b9c4",
  "status": "paid",
  "amount_rub": "10000.00",
  "fee_rub": "100.00",
  "rate": "88.70",
  "credited": { "amount": "111.61", "currency": "USD" },
  "external_id": "order-7731",
  "paid_at": "2026-11-12T10:33:18Z"
}

Вебхуки

О событиях мы сообщаем запросом POST на ваш адрес. Адрес вы указываете при подключении. Ответьте кодом 2xx в течение 10 секунд. Если ответа нет, мы повторяем отправку до 8 раз в течение 24 часов с растущим интервалом. Одно событие может прийти дважды — проверяйте id события.

События
card.createdКарта выпущена
card.topup.completedПополнение карты зачислено
card.frozen / card.unfrozenКарта заморожена или разморожена
card.closedКарта закрыта, остаток возвращён на баланс
card.3ds_codeКод 3-D Secure для подтверждения покупки — передайте его клиенту
transaction.authorizedПокупка одобрена, сумма заблокирована
transaction.settledПокупка проведена
transaction.declinedПокупка отклонена, в data.reason — причина
transaction.refundedВозврат от продавца зачислен на карту
sbp.invoice.paidСчёт СБП оплачен, сумма зачислена на баланс
sbp.invoice.expiredСчёт СБП истёк без оплаты
balance.depositedБаланс партнёра пополнен в USDT

Тело события

{
  "id": "evt_c7a1d5f0",
  "type": "transaction.settled",
  "created_at": "2026-11-12T09:30:05Z",
  "data": {
    "id": "txn_a41c93e0",
    "card_id": "card_9f2c1e7a",
    "type": "purchase",
    "status": "settled",
    "amount": "-20.00",
    "currency": "USD",
    "merchant": { "name": "OPENAI", "mcc": "5734", "country": "US" }
  }
}

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

Каждый запрос подписан. В заголовке X-Platina-Signature приходят время отправки t и подпись v1 — HMAC-SHA256 от строки t.тело с вашим секретом вебхуков. Отклоняйте запросы с неверной подписью и со временем старше 5 минут.

Node.js

import crypto from "node:crypto";

// header: значение X-Platina-Signature, вид "t=1794476405,v1=5f2a..."
// rawBody: тело запроса как строка, до JSON.parse
export function verify(header, rawBody, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Ошибки

При ошибке API возвращает код HTTP 4xx или 5xx и объект error. Поле request_id пришлите нам в бот, если нужна помощь с запросом.

Коды ошибок
HTTPcodeЧто значит
400invalid_requestНеверный параметр, в message — какой именно
401unauthorizedКлюч не передан или недействителен
402insufficient_balanceНедостаточно средств на балансе партнёра
402no_cards_remainingОплаченные карты закончились
403forbiddenМетод не входит в ваш тариф
404not_foundОбъект не найден
409card_not_activeКарта заморожена или закрыта
409idempotency_conflictТот же Idempotency-Key с другим телом запроса
429rate_limitedПревышен лимит запросов
500internal_errorОшибка на нашей стороне, запрос можно повторить

Пример

{
  "error": {
    "code": "insufficient_balance",
    "message": "Недостаточно средств на балансе партнёра",
    "request_id": "req_3b9e7f12"
  }
}

Лимиты

До 10 запросов в секунду на один ключ. При превышении API отвечает кодом 429, в заголовке Retry-After — через сколько секунд повторить. Списки отдаются страницами до 100 объектов.