C
CryptoPAY API

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

Принимайте платежи USDT TRC-20 на вашей платформе. Быстрая интеграция, подтверждение в блокчейне в реальном времени, автоматические уведомления через вебхуки.

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

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

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

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

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

Authorization: Bearer YOUR_API_KEY

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

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

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

CryptoPAY принимает платежи в фиатных валютах и конвертирует их в USDT TRC-20 по текущему рыночному курсу.

CodeВалютаМин. суммаИсточник курсаПримечания
RUB Российский рубль 1 ₽ CoinMarketCap (live, updated every 60s) По умолчанию. Наценка на курс может применяться индивидуально для каждого мерчанта.
USD Доллар США 1 $ CoinMarketCap (live, ≈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).

Подпись запросов (HMAC-SHA256)

Каждый POST запрос должен содержать поле a sign field. Это предотвращает подделку запросов и подтверждает вашу личность.

1

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

Возьмите все поля тела запроса кроме sign.

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

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

Когда платёж подтверждён в блокчейне TRON (~5 секунд), мы отправляем POST на ваш notify_url. Verify the sign и ответьте HTTP 200.

4

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

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

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

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

POST /api/v1/orders/create

Тело запроса

ПолеТипОбязательноОписание
order_idstringrequiredВаш уникальный идентификатор заказа (макс. 100 символов)
amountnumberrequiredСумма платежа в фиатной валюте (мин. 1 RUB / 1 USD)
currencystringoptional"RUB" (default) or "USD". See Валюты.
notify_urlstringoptionalURL вебхука для уведомлений о платежах (требуется HTTPS)
redirect_urlstringoptionalURL для перенаправления пользователя после оплаты
signstringrequiredПодпись HMAC-SHA256

Ответ

ПолеТипОписание
trade_idstringУникальный ID платежа CryptoPAY
order_idstringВаш ID заказа (возвращается обратно)
amountnumberОригинальная сумма в фиате
actual_amountnumberСумма USDT к оплате (4 знака после запятой)
currencystringКод валюты
rate_usednumberПрименённый курс обмена (фиат/USDT)
tokenstringАдрес TRON кошелька для оплаты
expiration_timeintegerUnix timestamp истечения заказа
payment_urlstringПеренаправьте пользователя сюда для оплаты

Примеры кода

curl -X POST https://cryptopay.webprompt.icu/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.0758,
    "currency": "RUB",
    "rate_used": 82.81,
    "token": "TN4JsVEyUBMcBjJbRGTriAPBDMjZaxnMet",
    "expiration_time": 1774131385,
    "payment_url": "https://cryptopay.webprompt.icu/pay/checkout-counter/20260322a1b2c3d4e5f67890"
  },
  "request_id": "req_abc123"
}

Отмена заказа

Отмена ожидающего (неоплаченного) заказа. Только заказы со статусом 0 (Ожидание) могут быть отменены.

POST /api/v1/orders/cancel

Тело запроса

ПолеТипОбязательноОписание
trade_idstringrequiredTrade ID CryptoPAY из ответа на создание
signstringrequiredПодпись HMAC-SHA256
curl -X POST https://cryptopay.webprompt.icu/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://cryptopay.webprompt.icu/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 оплаты.

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

When a payment is confirmed on the TRON blockchain, CryptoPAY sends a POST request to your notify_url with the payment details.

Тело колбэка

{
  "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_idstringCryptoPAY payment ID
order_idstringYour order ID
amountnumberОригинальная сумма в фиате
actual_amountnumberПолученная сумма USDT
currencystringКод валюты
rate_usednumberИспользованный курс обмена
tokenstringTRON кошелёк, принявший платёж
block_transaction_idstringХэш транзакции в блокчейне TRON
statusintegerAlways 1 (Paid)
signstringПодпись HMAC-SHA256 — verify this!
Верните HTTP 200 для подтверждения получения. Любой другой код вызовет повторную попытку. Ваш баланс зачисляется только после успешного подтверждения.

Проверка подписи вебхука

Всегда проверяйте поле sign в колбэках вебхуков, чтобы убедиться в подлинности запроса.

# Flask example
from flask import Flask, request, jsonify
import hmac, hashlib

app = Flask(__name__)
API_SECRET = "your_api_secret"

def verify_sign(payload: dict, secret: str) -> bool:
    received_sign = payload.pop("sign", "")
    sorted_str = "&".join(f"{k}={v}" for k, v in sorted(payload.items()))
    expected = hmac.new(secret.encode(), sorted_str.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(received_sign, expected)

@app.route("/webhook", methods=["POST"])
def webhook():
    data = request.json

    if not verify_sign(dict(data), API_SECRET):
        return "Invalid signature", 403

    trade_id = data["trade_id"]
    order_id = data["order_id"]
    amount_usdt = data["actual_amount"]

    # ✅ Mark order as paid in your database
    print(f"Payment confirmed: {order_id} — {amount_usdt} USDT")

    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. Администратор платформы также может запустить новый цикл повторов из панели администратора.

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

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

ЗначениеНазваниеОписание
0AwaitingЗаказ создан, ожидание оплаты USDT
1PaidПлатёж подтверждён в блокчейне TRON
2ExpiredЗаказ истёк (по умолчанию: 20 минут)
3CancelledОтменён мерчантом через API

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

ЗначениеНазваниеОписание
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

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

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

Обрабатывайте истечение заказов

Заказы истекают через 20 минут по умолчанию. Если пользователь не оплатил вовремя, создайте новый заказ.

Храните API секрет в безопасности

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

Документация CryptoPAY API CryptoPAY API Documentation · USDT TRC-20 Payment Gatewaymiddot; Платёжный шлюз USDT TRC-20