PlatinaPay API для мерчантов
Принимайте USDT, USDC и ещё восемь монет в десяти сетях: ETH, BNB, POL, SOL, BTC, LTC, TRX и GRAM. Быстрая интеграция, подтверждение в блокчейне в реальном времени, автоматические уведомления через вебхуки.
https://platinapay.orgВсе API запросы используют HTTPS. HTTP запросы перенаправляются.
Как это работает
Аутентификация
Каждый API запрос должен содержать ваш api_key в заголовке Authorization:
Authorization: Bearer YOUR_API_KEY
Вы получаете api_key и api_secret после одобрения аккаунта мерчанта администратором платформы. Найдите их в Личном кабинете → API ключи.
Поддерживаемые валюты
PlatinaPay принимает платежи в фиатных валютах и пересчитывает их в выбранную покупателем монету по текущему рыночному курсу. Монета и сеть выбираются отдельно — см. Сети и монеты.
| Code | Валюта | Мин. сумма | Источник курса | Примечания |
|---|---|---|---|---|
RUB |
Российский рубль | 1 ₽ | CoinMarketCap (обновляется каждые 60 с) | По умолчанию. Наценка на курс может применяться индивидуально для каждого мерчанта. |
USD |
Доллар США | 1 $ | CoinMarketCap (≈1.00) | Без наценки на курс. USDT ≈ USD. |
"currency": "RUB" or "currency": "USD" в теле запроса.
Если не указано, по умолчанию RUB. The amount field is always in the specified fiat currency — система автоматически рассчитает эквивалент в USDT.
Расчёт курса
// Example: 1000 RUB order at rate 83.21 RUB/USDT actual_usdt = 1000 / 83.21 = 12.0178 USDT // Example: 50 USD order at rate ~1.00 USD/USDT actual_usdt = 50 / 1.00 = 50.0000 USDT // The rate_used field in the response shows the exact rate applied. // Max order: 10,000 USDT equivalent (configurable by platform admin).
Сети и монеты
Десять монет в десяти сетях, двадцать семь сочетаний. Монета и сеть фиксируются при создании заказа: либо вы называете их сами, либо выбор отдаётся покупателю на платёжной странице.
| Сеть | Значение network | Монеты | Подтверждений | Ожидание |
|---|---|---|---|---|
| TRON | tron / trc20 | USDT, TRX | 19 | ~57 с |
| TON | ton | USDT, GRAM | 1 | секунды |
| BNB Smart Chain | bsc / bep20 | USDT, USDC, BNB, LTC, SOL | 15 | ~7 с |
| Polygon | polygon | USDT, USDC, POL | 30 | ~45 с |
| Arbitrum One | arbitrum | USDT, USDC, ETH | 20 | ~5 с |
| Base | base | USDT, USDC, ETH | 20 | ~40 с |
| Ethereum | ethereum / erc20 | USDT, USDC, ETH, TRX | 12 | ~2 мин 24 с |
| Solana | solana / sol | USDT, USDC, SOL | 32 | ~10 с |
| Bitcoin | bitcoin / btc | BTC | 2 | ~20 мин |
| Litecoin | litecoin / ltc | LTC | 6 | ~15 мин |
Поле network принимает как идентификатор сети (bsc, tron), так и привычное по биржам название (bep20, trc20, erc20) — в любом регистре. Для сетей, названных по своей монете, подходит и тикер (sol, btc, ltc). Если не передать сеть, заказ создаётся на TRON; если не передать монету — в USDT. USDT на TRON — единственное сочетание, в котором вебхук сохраняет прежние девять полей.
Bitcoin и Litecoin — исключение из ожиданий в секундах: там платёж набирает подтверждения десятки минут. Таймауты на своей стороне рассчитывайте по сети заказа, а не по TRON.
GET /api/v1/networks, он публичный и не требует подписи.Актуальный список
{
"status_code": 200,
"data": [
{
"network": "bsc",
"network_name": "BNB Smart Chain",
"standard": "BEP-20",
"network_label": "BEP-20 (BNB Smart Chain)",
"coin": "USDT",
"contract": "0x55d398326f99059fF775485246999027B3197955",
"decimals": 18,
"confirmations": 15,
"confirmation_seconds": 6,
"payment_window_seconds": 3600
},
{
"network": "bsc",
"network_name": "BNB Smart Chain",
"standard": "",
"network_label": "BNB Smart Chain (BNB)",
"coin": "BNB",
"contract": "",
"decimals": 18,
"confirmations": 15,
"confirmation_seconds": 6,
"payment_window_seconds": 3600
}
]
}
network_label — полное название сети для покупателя, вместе со скобками: "BEP-20 (BNB Smart Chain)", если на экране вывода биржи у сети своё название, и "TON (GRAM)" или "Bitcoin (BTC)", если нет — тогда в скобках монета, на которой работает сеть. Показывайте его как есть, не собирая из standard и network_name: эти поля остаются для тех, кому нужны части.
Возвращается пересечение трёх условий: что шлюз поддерживает, на что у него есть включённый кошелёк, и что принимаете вы — см. Настройки приёма.
Подпись запросов (HMAC-SHA256)
Каждый POST запрос должен содержать поле a sign field. Это предотвращает подделку запросов и подтверждает вашу личность.
Соберите поля
Возьмите все поля тела запроса кроме sign и пропустите поля с пустым значением. Числа подписываются в кратчайшей записи: 1000.00 превращается в 1000.
Отсортируйте по алфавиту
Отсортируйте имена полей по значению ASCII (A-Z, a-z).
Конкатенируйте
Join as key1=value1&key2=value2&...
HMAC-SHA256
Вычислите HMAC-SHA256 строки используя ваш api_secret как ключ. Результат (hex в нижнем регистре) — это ваше значение sign value.
Пример подписи
Given these fields and api_secret = "abc123secret":
// Input fields (excluding "sign"):
order_id = "ORDER-001"
amount = 1000
currency = "RUB"
notify_url = "https://example.com/callback"
// Step 2: Sort by key name
amount, currency, notify_url, order_id
// Step 3: Concatenate
"amount=1000¤cy=RUB¬ify_url=https://example.com/callback&order_id=ORDER-001"
// Step 4: HMAC-SHA256 with api_secret
sign = hmac_sha256("amount=1000¤cy=RUB¬ify_url=https://example.com/callback&order_id=ORDER-001", "abc123secret")
// → "e5f3a1b2c4d6..."
Процесс интеграции
Создайте заказ
Call POST /api/v1/orders/create с вашего бэкенда с суммой платежа и URL вебхука.
Перенаправьте пользователя
Перенаправьте пользователя на payment_url из ответа. Он увидит страницу оплаты с QR-кодом, адресом кошелька и таймером обратного отсчёта.
Получите вебхук
Когда платёж подтверждён в блокчейне, мы отправляем POST на ваш notify_url. Проверьте поле sign и ответьте HTTP 200.
Выполните заказ
Отметьте заказ как оплаченный в вашей системе. Пользователь будет автоматически перенаправлен на ваш redirect_url.
Создание заказа
Создание нового платёжного заказа. Возвращает URL для перенаправления пользователя на страницу оплаты.
Тело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| order_id | string | required | Ваш уникальный идентификатор заказа (макс. 100 символов) |
| amount | number | required | Сумма платежа в фиатной валюте (мин. 1 RUB / 1 USD) |
| currency | string | optional | "RUB" (по умолчанию) или "USD". См. Валюты. |
| network | string | optional | Сеть — идентификатор или биржевое название: tron/trc20, bsc/bep20, solana/sol и так далее. По умолчанию TRON. См. Сети и монеты |
| coin | string | optional | "USDT" (по умолчанию) |
| notify_url | string | optional | URL вебхука для уведомлений о платежах (требуется HTTPS) |
| redirect_url | string | optional | URL для перенаправления пользователя после оплаты |
| sign | string | required | Подпись HMAC-SHA256 |
Ответ
| Поле | Тип | Описание |
|---|---|---|
| trade_id | string | Уникальный ID платежа PlatinaPay |
| order_id | string | Ваш ID заказа (возвращается обратно) |
| amount | number | Оригинальная сумма в фиате |
| actual_amount | number | Сумма к оплате в выбранной монете. Знаков после запятой зависит от монеты: восемь у BTC; шесть у ETH, BNB, POL, SOL и LTC; четыре у USDT, USDC, GRAM и TRX. Разбирайте как число, а не как строку |
| currency | string | Код валюты |
| rate_used | number | Применённый курс обмена (фиат/USDT) |
| token | string | Адрес кошелька для оплаты, в выбранной сети |
| network | string | Сеть заказа: tron, ton, bsc, polygon, arbitrum, base, ethereum, solana, bitcoin, litecoin |
| coin | string | Монета заказа |
| expiration_time | integer | Unix timestamp истечения заказа |
| payment_url | string | Перенаправьте пользователя сюда для оплаты |
Примеры кода
curl -X POST https://platinapay.org/api/v1/orders/create \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"order_id": "ORDER-001",
"amount": 1000.00,
"currency": "RUB",
"notify_url": "https://yoursite.com/webhook",
"redirect_url": "https://yoursite.com/success",
"sign": "COMPUTED_HMAC_SHA256_HEX"
}'
Пример ответа
{
"status_code": 200,
"message": "success",
"data": {
"trade_id": "20260322a1b2c3d4e5f67890",
"order_id": "ORDER-001",
"amount": 1000.00,
"actual_amount": 12.075800,
"currency": "RUB",
"rate_used": 82.81,
"token": "TN4JsVEyUBMcBjJbRGTriAPBDMjZaxnMet",
"expiration_time": 1774131385,
"payment_url": "https://platinapay.org/pay/checkout-counter/20260322a1b2c3d4e5f67890"
},
"request_id": "req_abc123"
}
Заказ с выбором сети покупателем
Создаёт заказ, монету и сеть для которого выбирает покупатель на нашей платёжной странице. Подходит, если вы не хотите вести список сетей у себя.
Принимает те же поля, что и создание заказа, кроме network и coin — в этом и смысл: они ещё не известны.
{
"status_code": 200,
"data": {
"trade_id": "20260322a1b2c3d4e5f67890",
"order_id": "ORDER-001",
"amount": 1000.00,
"currency": "RUB",
"expiration_time": 1774131385,
"payment_url": "https://platinapay.org/pay/checkout-counter/20260322a1b2c3d4e5f67890"
}
}
В ответе нет token, actual_amount и rate_used: пока покупатель не выбрал монету и сеть, ни адреса, ни курса не существует. Заказ находится в статусе 4.
expiration_time здесь — единый срок жизни заказа с момента создания: он покрывает и выбор монеты и сети, и оплату. Выбор актива его не перезапускает — у плательщика остаётся то время, что не истекло. По умолчанию это один час.Дальше всё как обычно: отправьте покупателя на payment_url, а результат узнайте из вебхука или опросом запроса статуса. Если сейчас нет ни одной доступной сети, эндпоинт вернёт ошибку 10010 вместо того, чтобы отправить покупателя на страницу, где нечего выбрать.
Отмена заказа
Отмена ожидающего (неоплаченного) заказа. Только заказы со статусом 0 (Ожидание) могут быть отменены.
Тело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| trade_id | string | required | Trade ID PlatinaPay из ответа на создание |
| sign | string | required | Подпись HMAC-SHA256 |
curl -X POST https://platinapay.org/api/v1/orders/cancel \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"trade_id": "20260322a1b2c3d4e5f67890", "sign": "HMAC_HEX"}'
Запрос статуса заказа
Получение текущего статуса и деталей заказа.
curl https://platinapay.org/api/v1/orders/query/20260322a1b2c3d4e5f67890 \ -H "Authorization: Bearer YOUR_API_KEY"
Пример ответа
{
"status_code": 200,
"data": {
"trade_id": "20260322a1b2c3d4e5f67890",
"order_id": "ORDER-001",
"amount": 1000.00,
"actual_amount": 12.0758,
"currency": "RUB",
"rate_used": 82.81,
"token": "TN4JsVEyUBMcBjJbRGTriAPBDMjZaxnMet",
"status": 1,
"block_transaction_id": "7f3a2b1c...",
"callback_status": 1,
"commission": 0.2415,
"net_amount": 11.8343,
"created_at": "2026-03-22T12:00:00Z",
"paid_at": "2026-03-22T12:03:45Z",
"expiration_time": null,
"callback_payload": { "..." }
}
}
Статус оплаты (поллинг)
Лёгкий эндпоинт для проверки получения платежа. Полезен для поллинга на фронтенде, пока пользователь на странице оплаты. Аутентификация не требуется.
// Response
{"status_code": 200, "data": {"status": 1}}
Вебхук колбэк
Когда платёж подтверждён в блокчейне, PlatinaPay отправляет POST на ваш notify_url с деталями платежа.
network и coin.Тело подписано, поэтому набор полей — часть контракта. Если ваш обработчик перечисляет девять имён полей списком в коде, он посчитает подпись по девяти, а шлюз подписал одиннадцать: каждый такой колбэк не пройдёт проверку, платёж будет выглядеть неоплаченным, а деньги уже придут на кошелёк. Обработчик, который подписывает всё пришедшее, править не нужно — примеры ниже написаны именно так.
Нужна одна форма на всех сетях? Закрепите версию 2 в настройках приёма — тогда network и coin будут приходить и в заказах USDT на TRON.
Тело колбэка
Приходит как application/x-www-form-urlencoded, поэтому все значения — строки. В запросе это одна строка, здесь она разбита для удобства чтения:
trade_id=20260322a1b2c3d4e5f67890 &order_id=ORDER-001 &amount=1000.00 &actual_amount=12.0758 ¤cy=RUB &rate_used=82.81 &token=TN4JsVEyUBMcBjJbRGTriAPBDMjZaxnMet &block_transaction_id=7f3a2b1c4d5e6f7890abcdef... &status=1 &sign=a3f2b1c4d5e6f7890123456789abcdef...
| Поле | Тип | Описание |
|---|---|---|
| trade_id | string | Идентификатор платежа PlatinaPay |
| order_id | string | Ваш идентификатор заказа |
| amount | number | Оригинальная сумма в фиате |
| actual_amount | number | Полученная сумма в монете заказа. Знаков после запятой зависит от монеты: восемь у BTC; шесть у ETH, BNB, POL, SOL и LTC; четыре у USDT, USDC, GRAM и TRX |
| currency | string | Код валюты |
| rate_used | number | Использованный курс обмена |
| token | string | Адрес, на который пришёл платёж |
| block_transaction_id | string | Хэш транзакции в блокчейне |
| status | integer | Всегда 1 (оплачено) |
| network | string | Сеть заказа, например ton или bsc. Не приходит в заказах USDT на TRON |
| coin | string | Монета заказа: USDT, USDC, ETH, BNB, POL, GRAM, SOL, BTC, LTC, TRX. Не приходит в заказах USDT на TRON |
| sign | string | Подпись HMAC-SHA256 — обязательно проверяйте! |
network и coin, а тестовый вебхук из кабинета добавляет is_test, который в подпись не входит. Проверка по фиксированному списку даст другую подпись, и корректный вебхук будет отклонён. То же касается любых полей, которые появятся позже.Проверка подписи вебхука
Всегда проверяйте поле sign в колбэках вебхуков, чтобы убедиться в подлинности запроса.
# Flask example
from flask import Flask, request
import hmac, hashlib
app = Flask(__name__)
API_SECRET = "your_api_secret"
def verify_sign(fields: dict, secret: str) -> bool:
received = fields.get("sign", "")
# Every field that arrived except sign and is_test, skipping empty ones
signed = {k: v for k, v in fields.items() if k not in ("sign", "is_test") and v != ""}
param_str = "&".join(f"{k}={v}" for k, v in sorted(signed.items()))
expected = hmac.new(secret.encode(), param_str.encode(), hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), received.encode())
@app.route("/webhook", methods=["POST"])
def webhook():
data = request.form.to_dict() # the webhook is form-urlencoded, not JSON
if not verify_sign(data, API_SECRET):
return "Invalid signature", 403
# ✅ Mark the order paid in your database, once per trade_id
print(f"Payment confirmed: order {data['order_id']}, trade {data['trade_id']}")
return "ok", 200 # Must return 200!
Политика повторов
Если ваш сервер не ответит HTTP 200, мы повторяем с экспоненциальной задержкой:
| Попытка | Задержка | Всего прошло |
|---|---|---|
| 1st | Немедленно | 0 min |
| 2nd | 1 минута | 1 min |
| 3rd | 2 минуты | 3 min |
| 4th | 5 минут | 8 min |
| 5th | 10 минут | 18 min |
| 6th | 15 минут | 33 min |
| 7th (final) | 30 минут | ~63 min |
После 7 неудачных попыток колбэк помечается как неудачный. Вы всё ещё можете запросить статус заказа через API. Администратор платформы также может запустить новый цикл повторов из панели администратора.
Настройки приёма
Какие монеты и сети вы принимаете и в какой форме получаете колбэк. Настраивается в личном кабинете, раздел «Настройки приёма», либо через API.
| Поле | Тип | Описание |
|---|---|---|
| available | array | Всё, что шлюз может принять сейчас. Это меню, а не ваш выбор |
| allowed_assets | array | Что принимаете вы, строками вида "USDT.bsc". Пустой список означает «всё», а не «ничего» |
| callback_version | integer | 0 — форма по сети заказа (по умолчанию), 1 — всегда девять полей v1, 2 — всегда с network и coin |
PUT /merchant/api/payment-settings
{
"allowed_assets": ["USDT.tron", "USDT.ton", "USDT.bsc", "USDC.bsc"],
"callback_version": 2
}
allowed_assets — это «принимаю всё», включая сети, которые появятся позже. Хотите строго определённый набор — перечислите его явно.Ограничение списка сужает и то, что возвращает GET /api/v1/networks для ваших заказов, и то, что предлагает покупателю платёжная страница. Запись про актив, которого шлюз сейчас принять не может, не отвергается — она просто ни с чем не совпадает, пока для него не появится кошелёк.
Закрепили callback_version: 1 и всё равно нужна сеть? Она есть в ответе запроса статуса — поля network и coin приходят там на всех сетях, потому что этот ответ не подписывается.
Статусы заказов и колбэков
Статус заказа
| Значение | Название | Описание |
|---|---|---|
| 0 | Awaiting | Сеть выбрана, адрес выдан, ожидание оплаты |
| 1 | Paid | Платёж подтверждён в блокчейне |
| 2 | Expired | Заказ истёк (окно оплаты — 1 час) |
| 3 | Cancelled | Отменён мерчантом через API |
| 4 | Awaiting choice | Покупатель ещё не выбрал монету и сеть — адреса и суммы пока нет. Только для заказов из /orders/checkout |
Статус колбэка
| Значение | Название | Описание |
|---|---|---|
| 0 | Pending | Ещё не отправлялся |
| 1 | Delivered | Мерчант вернул HTTP 200 |
| 2 | Retrying | Доставка в процессе (цикл повторов) |
| 3 | Failed | Все 7 попыток исчерпаны |
Коды ошибок
| Code | Название | Описание |
|---|---|---|
10001 | INVALID_REQUEST | Отсутствующие или невалидные параметры запроса |
10002 | UNAUTHORIZED | Невалидный API ключ или подпись |
10003 | MERCHANT_SUSPENDED | Ваш аккаунт заблокирован |
10004 | ORDER_ALREADY_EXISTS | Дублирующий order_id для этого мерчанта |
10005 | PAY_AMOUNT_TOO_SMALL | Сумма ниже минимума (1 RUB / 1 USD) |
10006 | PAY_AMOUNT_TOO_LARGE | Сумма превышает максимум (10 000 USDT эквивалент) |
10007 | RATE_NOT_AVAILABLE | Курс обмена временно недоступен |
10008 | ORDER_NOT_CANCELLABLE | Заказ не в статусе ожидания |
10009 | NOT_AVAILABLE_AMOUNT | Нет свободного платёжного слота (все суммы заняты) |
10010 | NOT_AVAILABLE_WALLET | Нет доступного адреса кошелька |
10011 | INSUFFICIENT_BALANCE | Недостаточно средств для вывода |
10012 | ORDER_NOT_FOUND | Заказ не существует или принадлежит другому мерчанту |
10013 | ACCOUNT_PENDING | Аккаунт ожидает одобрения администратора |
10014 | ACCOUNT_REJECTED | Регистрация аккаунта была отклонена |
10015 | TWO_FACTOR_REQUIRED | Требуется верификация 2FA |
10016 | UNSUPPORTED_NETWORK | Неизвестная сеть в поле network — берите значения из /api/v1/networks |
10017 | NETWORK_UNAVAILABLE | Сеть временно недоступна — предложите другую или повторите позже |
Формат ответа с ошибкой
{
"status_code": 10004,
"message": "order_id already exists for this merchant",
"data": null,
"request_id": "req_abc123"
}
Лимиты запросов
| Эндпоинт | Лимит | Область |
|---|---|---|
POST /api/v1/orders/create | 100 req/min | На API ключ |
POST /api/v1/orders/create | 1,000 req/min | Глобально (все мерчанты) |
All /api/v1/* endpoints | 300 req/min | На API ключ |
GET /pay/status/* | 60 req/min | На IP адрес |
При превышении лимита API возвращает HTTP 429 (Too Many Requests).
Лучшие практики
Всегда проверяйте подписи вебхуков
Use constant-time comparison (hmac.compare_digest in Python, crypto.timingSafeEqual in Node.js) для предотвращения timing-атак.
Сделайте обработчик вебхуков идемпотентным
Мы можем отправить один и тот же колбэк несколько раз. Проверяйте, не выполнен ли уже заказ перед обработкой. Use trade_id as the idempotency key.
Отвечайте на вебхуки быстро
Верните HTTP 200 в течение 30 секунд. Выполняйте тяжёлую обработку асинхронно после подтверждения.
Используйте уникальные order_id
Each order_id должен быть уникальным для каждого мерчанта. Повторное использование order_id вернёт ошибку 10004.
Обрабатывайте истечение заказов
На весь заказ — и выбор монеты и сети, и сам перевод — даётся один час с момента создания: это один общий таймер, а не отдельное окно на выбор и на оплату. Если часа не хватает, на странице оплаты есть кнопка, добавляющая ещё 30 минут, и сумма при этом не пересчитывается. Всего заказ живёт не дольше 4 часов.
Храните API секрет в безопасности
Храните его в переменных окружения или менеджере секретов. Перегенерируйте через панель мерчанта в случае компрометации.