PlatinaPay
PlatinaPay API

PlatinaPay API для мерчантов

Принимайте USDT, USDC и ещё восемь монет в десяти сетях: ETH, BNB, POL, SOL, BTC, LTC, TRX и GRAM. Быстрая интеграция, подтверждение в блокчейне в реальном времени, автоматические уведомления через вебхуки.

Базовый URL: https://platinapay.org
Все API запросы используют HTTPS. HTTP запросы перенаправляются.

Как это работает

1. Создание заказа
→
2. Редирект на страницу оплаты
→
3. Оплата в выбранной сети
→
4. Подтверждение в блокчейне
→
5. Вебхук колбэк

Аутентификация

Каждый API запрос должен содержать ваш api_key в заголовке Authorization:

Authorization: Bearer YOUR_API_KEY

Вы получаете api_key и api_secret после одобрения аккаунта мерчанта администратором платформы. Найдите их в Личном кабинете → API ключи.

Держите api_secret в секрете. Никогда не размещайте его в клиентском коде, мобильных приложениях или публичных репозиториях. Все API вызовы должны выполняться с вашего бэкенд-сервера.

Поддерживаемые валюты

PlatinaPay принимает платежи в фиатных валютах и пересчитывает их в выбранную покупателем монету по текущему рыночному курсу. Монета и сеть выбираются отдельно — см. Сети и монеты.

CodeВалютаМин. суммаИсточник курсаПримечания
RUB Российский рубль 1 ₽ CoinMarketCap (обновляется каждые 60 с) По умолчанию. Наценка на курс может применяться индивидуально для каждого мерчанта.
USD Доллар США 1 $ CoinMarketCap (≈1.00) Без наценки на курс. USDT ≈ USD.
Как использовать: Pass "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МонетыПодтвержденийОжидание
TRONtron / trc20USDT, TRX19~57 с
TONtonUSDT, GRAM1секунды
BNB Smart Chainbsc / bep20USDT, USDC, BNB, LTC, SOL15~7 с
PolygonpolygonUSDT, USDC, POL30~45 с
Arbitrum OnearbitrumUSDT, USDC, ETH20~5 с
BasebaseUSDT, USDC, ETH20~40 с
Ethereumethereum / erc20USDT, USDC, ETH, TRX12~2 мин 24 с
Solanasolana / solUSDT, USDC, SOL32~10 с
Bitcoinbitcoin / btcBTC2~20 мин
Litecoinlitecoin / ltcLTC6~15 мин

Поле network принимает как идентификатор сети (bsc, tron), так и привычное по биржам название (bep20, trc20, erc20) — в любом регистре. Для сетей, названных по своей монете, подходит и тикер (sol, btc, ltc). Если не передать сеть, заказ создаётся на TRON; если не передать монету — в USDT. USDT на TRON — единственное сочетание, в котором вебхук сохраняет прежние девять полей.

Bitcoin и Litecoin — исключение из ожиданий в секундах: там платёж набирает подтверждения десятки минут. Таймауты на своей стороне рассчитывайте по сети заказа, а не по TRON.

Список сетей меняется по мере включения кошельков. Не зашивайте его в код — читайте GET /api/v1/networks, он публичный и не требует подписи.

Актуальный список

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. Это предотвращает подделку запросов и подтверждает вашу личность.

1

Соберите поля

Возьмите все поля тела запроса кроме sign и пропустите поля с пустым значением. Числа подписываются в кратчайшей записи: 1000.00 превращается в 1000.

2

Отсортируйте по алфавиту

Отсортируйте имена полей по значению ASCII (A-Z, a-z).

3

Конкатенируйте

Join as key1=value1&key2=value2&...

4

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..."

Процесс интеграции

1

Создайте заказ

Call POST /api/v1/orders/create с вашего бэкенда с суммой платежа и URL вебхука.

2

Перенаправьте пользователя

Перенаправьте пользователя на payment_url из ответа. Он увидит страницу оплаты с QR-кодом, адресом кошелька и таймером обратного отсчёта.

3

Получите вебхук

Когда платёж подтверждён в блокчейне, мы отправляем POST на ваш notify_url. Проверьте поле sign и ответьте HTTP 200.

4

Выполните заказ

Отметьте заказ как оплаченный в вашей системе. Пользователь будет автоматически перенаправлен на ваш redirect_url.

Создание заказа

Создание нового платёжного заказа. Возвращает URL для перенаправления пользователя на страницу оплаты.

POST /api/v1/orders/create

Тело запроса

ПолеТипОбязательноОписание
order_idstringrequiredВаш уникальный идентификатор заказа (макс. 100 символов)
amountnumberrequiredСумма платежа в фиатной валюте (мин. 1 RUB / 1 USD)
currencystringoptional"RUB" (по умолчанию) или "USD". См. Валюты.
networkstringoptionalСеть — идентификатор или биржевое название: tron/trc20, bsc/bep20, solana/sol и так далее. По умолчанию TRON. См. Сети и монеты
coinstringoptional"USDT" (по умолчанию)
notify_urlstringoptionalURL вебхука для уведомлений о платежах (требуется HTTPS)
redirect_urlstringoptionalURL для перенаправления пользователя после оплаты
signstringrequiredПодпись HMAC-SHA256

Ответ

ПолеТипОписание
trade_idstringУникальный ID платежа PlatinaPay
order_idstringВаш ID заказа (возвращается обратно)
amountnumberОригинальная сумма в фиате
actual_amountnumberСумма к оплате в выбранной монете. Знаков после запятой зависит от монеты: восемь у BTC; шесть у ETH, BNB, POL, SOL и LTC; четыре у USDT, USDC, GRAM и TRX. Разбирайте как число, а не как строку
currencystringКод валюты
rate_usednumberПрименённый курс обмена (фиат/USDT)
tokenstringАдрес кошелька для оплаты, в выбранной сети
networkstringСеть заказа: tron, ton, bsc, polygon, arbitrum, base, ethereum, solana, bitcoin, litecoin
coinstringМонета заказа
expiration_timeintegerUnix timestamp истечения заказа
payment_urlstringПеренаправьте пользователя сюда для оплаты

Примеры кода

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"
}

Заказ с выбором сети покупателем

Создаёт заказ, монету и сеть для которого выбирает покупатель на нашей платёжной странице. Подходит, если вы не хотите вести список сетей у себя.

POST /api/v1/orders/checkout

Принимает те же поля, что и создание заказа, кроме 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 (Ожидание) могут быть отменены.

POST /api/v1/orders/cancel

Тело запроса

ПолеТипОбязательноОписание
trade_idstringrequiredTrade ID PlatinaPay из ответа на создание
signstringrequiredПодпись 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"}'

Запрос статуса заказа

Получение текущего статуса и деталей заказа.

GET /api/v1/orders/query/{trade_id}
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": { "..." }
  }
}

Статус оплаты (поллинг)

Лёгкий эндпоинт для проверки получения платежа. Полезен для поллинга на фронтенде, пока пользователь на странице оплаты. Аутентификация не требуется.

GET /pay/status/{trade_id}
// Response
{"status_code": 200, "data": {"status": 1}}
Лимит: 60 запросов/минуту на IP. Страница оплаты уже опрашивает этот эндпоинт автоматически — вам не нужно реализовывать поллинг самостоятельно, если вы не создаёте собственный UI оплаты.

Вебхук колбэк

Когда платёж подтверждён в блокчейне, PlatinaPay отправляет POST на ваш notify_url с деталями платежа.

Набор полей зависит от монеты и сети заказа. Заказы в USDT на TRON приходят с теми же девятью полями, что и всегда — байт в байт. Любая другая монета или сеть, включая TRX на TRON, несёт ещё два: 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
&currency=RUB
&rate_used=82.81
&token=TN4JsVEyUBMcBjJbRGTriAPBDMjZaxnMet
&block_transaction_id=7f3a2b1c4d5e6f7890abcdef...
&status=1
&sign=a3f2b1c4d5e6f7890123456789abcdef...
ПолеТипОписание
trade_idstringИдентификатор платежа PlatinaPay
order_idstringВаш идентификатор заказа
amountnumberОригинальная сумма в фиате
actual_amountnumberПолученная сумма в монете заказа. Знаков после запятой зависит от монеты: восемь у BTC; шесть у ETH, BNB, POL, SOL и LTC; четыре у USDT, USDC, GRAM и TRX
currencystringКод валюты
rate_usednumberИспользованный курс обмена
tokenstringАдрес, на который пришёл платёж
block_transaction_idstringХэш транзакции в блокчейне
statusintegerВсегда 1 (оплачено)
networkstringСеть заказа, например ton или bsc. Не приходит в заказах USDT на TRON
coinstringМонета заказа: USDT, USDC, ETH, BNB, POL, GRAM, SOL, BTC, LTC, TRX. Не приходит в заказах USDT на TRON
signstringПодпись HMAC-SHA256 — обязательно проверяйте!
Верните HTTP 200 для подтверждения получения. Любой другой код вызовет повторную попытку. Ваш баланс зачисляется только после успешного подтверждения.
Подписывайте все поля, которые пришли, а не заранее заданный список. Заказы во всём, кроме USDT на TRON, несут два дополнительных поля, 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
2nd1 минута1 min
3rd2 минуты3 min
4th5 минут8 min
5th10 минут18 min
6th15 минут33 min
7th (final)30 минут~63 min

После 7 неудачных попыток колбэк помечается как неудачный. Вы всё ещё можете запросить статус заказа через API. Администратор платформы также может запустить новый цикл повторов из панели администратора.

Настройки приёма

Какие монеты и сети вы принимаете и в какой форме получаете колбэк. Настраивается в личном кабинете, раздел «Настройки приёма», либо через API.

GET /merchant/api/payment-settings
PUT /merchant/api/payment-settings
ПолеТипОписание
availablearrayВсё, что шлюз может принять сейчас. Это меню, а не ваш выбор
allowed_assetsarrayЧто принимаете вы, строками вида "USDT.bsc". Пустой список означает «всё», а не «ничего»
callback_versioninteger0 — форма по сети заказа (по умолчанию), 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 приходят там на всех сетях, потому что этот ответ не подписывается.

Статусы заказов и колбэков

Статус заказа

ЗначениеНазваниеОписание
0AwaitingСеть выбрана, адрес выдан, ожидание оплаты
1PaidПлатёж подтверждён в блокчейне
2ExpiredЗаказ истёк (окно оплаты — 1 час)
3CancelledОтменён мерчантом через API
4Awaiting choiceПокупатель ещё не выбрал монету и сеть — адреса и суммы пока нет. Только для заказов из /orders/checkout

Статус колбэка

ЗначениеНазваниеОписание
0PendingЕщё не отправлялся
1DeliveredМерчант вернул HTTP 200
2RetryingДоставка в процессе (цикл повторов)
3FailedВсе 7 попыток исчерпаны

Коды ошибок

CodeНазваниеОписание
10001INVALID_REQUESTОтсутствующие или невалидные параметры запроса
10002UNAUTHORIZEDНевалидный API ключ или подпись
10003MERCHANT_SUSPENDEDВаш аккаунт заблокирован
10004ORDER_ALREADY_EXISTSДублирующий order_id для этого мерчанта
10005PAY_AMOUNT_TOO_SMALLСумма ниже минимума (1 RUB / 1 USD)
10006PAY_AMOUNT_TOO_LARGEСумма превышает максимум (10 000 USDT эквивалент)
10007RATE_NOT_AVAILABLEКурс обмена временно недоступен
10008ORDER_NOT_CANCELLABLEЗаказ не в статусе ожидания
10009NOT_AVAILABLE_AMOUNTНет свободного платёжного слота (все суммы заняты)
10010NOT_AVAILABLE_WALLETНет доступного адреса кошелька
10011INSUFFICIENT_BALANCEНедостаточно средств для вывода
10012ORDER_NOT_FOUNDЗаказ не существует или принадлежит другому мерчанту
10013ACCOUNT_PENDINGАккаунт ожидает одобрения администратора
10014ACCOUNT_REJECTEDРегистрация аккаунта была отклонена
10015TWO_FACTOR_REQUIREDТребуется верификация 2FA
10016UNSUPPORTED_NETWORKНеизвестная сеть в поле network — берите значения из /api/v1/networks
10017NETWORK_UNAVAILABLEСеть временно недоступна — предложите другую или повторите позже

Формат ответа с ошибкой

{
  "status_code": 10004,
  "message": "order_id already exists for this merchant",
  "data": null,
  "request_id": "req_abc123"
}

Лимиты запросов

ЭндпоинтЛимитОбласть
POST /api/v1/orders/create100 req/minНа API ключ
POST /api/v1/orders/create1,000 req/minГлобально (все мерчанты)
All /api/v1/* endpoints300 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 секрет в безопасности

Храните его в переменных окружения или менеджере секретов. Перегенерируйте через панель мерчанта в случае компрометации.

Документация PlatinaPay API · Криптовалютный платёжный шлюз