CryptoPAY API для мерчантов
Принимайте платежи USDT TRC-20 на вашей платформе. Быстрая интеграция, подтверждение в блокчейне в реальном времени, автоматические уведомления через вебхуки.
https://cryptopay.webprompt.icuВсе API запросы используют HTTPS. HTTP запросы перенаправляются.
Как это работает
Аутентификация
Каждый API запрос должен содержать your api_key в заголовке Authorization:
Authorization: Bearer YOUR_API_KEY
Вы получаете api_key and api_secret после одобрения аккаунта мерчанта администратором платформы. Найдите их в Личном кабинете → API ключи.
Поддерживаемые валюты
CryptoPAY принимает платежи в фиатных валютах и конвертирует их в USDT TRC-20 по текущему рыночному курсу.
| Code | Валюта | Мин. сумма | Источник курса | Примечания |
|---|---|---|---|---|
RUB |
Российский рубль | 1 ₽ | CoinMarketCap (live, updated every 60s) | По умолчанию. Наценка на курс может применяться индивидуально для каждого мерчанта. |
USD |
Доллар США | 1 $ | CoinMarketCap (live, ≈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).
Подпись запросов (HMAC-SHA256)
Каждый POST запрос должен содержать поле a sign field. Это предотвращает подделку запросов и подтверждает вашу личность.
Соберите поля
Возьмите все поля тела запроса кроме sign.
Отсортируйте по алфавиту
Отсортируйте имена полей по значению 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-кодом, адресом кошелька и таймером обратного отсчёта.
Получите вебхук
Когда платёж подтверждён в блокчейне TRON (~5 секунд), мы отправляем POST на ваш notify_url. Verify the sign и ответьте HTTP 200.
Выполните заказ
Отметьте заказ как оплаченный в вашей системе. Пользователь будет автоматически перенаправлен на ваш redirect_url.
Создание заказа
Создание нового платёжного заказа. Возвращает URL для перенаправления пользователя на страницу оплаты.
Тело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| order_id | string | required | Ваш уникальный идентификатор заказа (макс. 100 символов) |
| amount | number | required | Сумма платежа в фиатной валюте (мин. 1 RUB / 1 USD) |
| currency | string | optional | "RUB" (default) or "USD". See Валюты. |
| notify_url | string | optional | URL вебхука для уведомлений о платежах (требуется HTTPS) |
| redirect_url | string | optional | URL для перенаправления пользователя после оплаты |
| sign | string | required | Подпись HMAC-SHA256 |
Ответ
| Поле | Тип | Описание |
|---|---|---|
| trade_id | string | Уникальный ID платежа CryptoPAY |
| order_id | string | Ваш ID заказа (возвращается обратно) |
| amount | number | Оригинальная сумма в фиате |
| actual_amount | number | Сумма USDT к оплате (4 знака после запятой) |
| currency | string | Код валюты |
| rate_used | number | Применённый курс обмена (фиат/USDT) |
| token | string | Адрес TRON кошелька для оплаты |
| expiration_time | integer | Unix timestamp истечения заказа |
| payment_url | string | Перенаправьте пользователя сюда для оплаты |
Примеры кода
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 (Ожидание) могут быть отменены.
Тело запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| trade_id | string | required | Trade ID CryptoPAY из ответа на создание |
| sign | string | required | Подпись 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"}'
Запрос статуса заказа
Получение текущего статуса и деталей заказа.
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": { "..." }
}
}
Статус оплаты (поллинг)
Лёгкий эндпоинт для проверки получения платежа. Полезен для поллинга на фронтенде, пока пользователь на странице оплаты. Аутентификация не требуется.
// Response
{"status_code": 200, "data": {"status": 1}}
Вебхук колбэк
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_id | string | CryptoPAY payment ID |
| order_id | string | Your order ID |
| amount | number | Оригинальная сумма в фиате |
| actual_amount | number | Полученная сумма USDT |
| currency | string | Код валюты |
| rate_used | number | Использованный курс обмена |
| token | string | TRON кошелёк, принявший платёж |
| block_transaction_id | string | Хэш транзакции в блокчейне TRON |
| status | integer | Always 1 (Paid) |
| sign | string | Подпись HMAC-SHA256 — verify this! |
Проверка подписи вебхука
Всегда проверяйте поле 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 |
| 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. Администратор платформы также может запустить новый цикл повторов из панели администратора.
Статусы заказов и колбэков
Статус заказа
| Значение | Название | Описание |
|---|---|---|
| 0 | Awaiting | Заказ создан, ожидание оплаты USDT |
| 1 | Paid | Платёж подтверждён в блокчейне TRON |
| 2 | Expired | Заказ истёк (по умолчанию: 20 минут) |
| 3 | Cancelled | Отменён мерчантом через API |
Статус колбэка
| Значение | Название | Описание |
|---|---|---|
| 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 |
Формат ответа с ошибкой
{
"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.
Обрабатывайте истечение заказов
Заказы истекают через 20 минут по умолчанию. Если пользователь не оплатил вовремя, создайте новый заказ.
Храните API секрет в безопасности
Храните его в переменных окружения или менеджере секретов. Перегенерируйте через панель мерчанта в случае компрометации.