Справочник по API

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

Стартовый шаблон Next.js

Готовое приложение Next.js с авторизацией, страницей тарифов и предварительно настроенными платежами ChainPay. Клонируйте и запустите за 5 минут.

Открыть на GitHub

Быстрый старт

Принимайте криптоплатежи в три шага — без знаний блокчейна.

1

Создайте платёжный заказ

Node.js
const response = await fetch("https://chainpay.pro/api/v1/orders", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    amount: 29.99,
    currency: "USDT",
    chain: "trc20",
    externalId: "order_abc123",           // your internal order ID
    metadata: { userId: "user_456" }      // arbitrary JSON, returned in webhook
  })
});

const order = await response.json();
// order.checkoutUrl  → redirect user here
// order.payAddress   → or show the address directly
2

Перенаправьте пользователя на страницу оплаты

JavaScript
// Server-side redirect
res.redirect(order.checkoutUrl);

// Or client-side
window.location.href = order.checkoutUrl;
3

Получите вебхук, когда платёж подтверждён

Тело вебхука (POST на ваш сервер)
{
  "event": "payment.completed",
  "orderId": "ord_a1b2c3d4e5f6",
  "externalId": "order_abc123",
  "amount": "29.99",
  "netAmount": "29.75",          // after 0.8% fee
  "currency": "USDT",
  "chain": "trc20",
  "txHash": "e3b0c44298fc1c149afb...",
  "completedAt": "2026-03-22T08:15:00Z",
  "metadata": { "userId": "user_456" }
}

Проверьте заголовок X-ChainPay-Signature перед обработкой. Код проверки см. в разделе .

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

Все запросы к API должны содержать ваш API-ключ в виде Bearer-токена.

HTTP-заголовок
Authorization: Bearer sk_live_YOUR_API_KEY
Пример cURL
curl -X POST https://chainpay.pro/api/v1/orders \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10, "currency": "USDT", "chain": "trc20"}'
Префикс ключаОкружениеБлокчейн
sk_live_…ПродакшенРеальные транзакции
sk_test_…ПесочницаРеальные средства не перемещаются
Безопасность: Никогда не раскрывайте API-ключ в клиентском коде или публичных репозиториях. Храните его в переменной окружения и вызывайте API только со своего бэкенда.

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

POSThttps://chainpay.pro/api/v1/orders

Параметры запроса

ПараметрТипОбязательноОписание
amountnumberобязательноСумма платежа в USD (например, 29.99). Эквивалентная сумма в крипто рассчитывается по текущему рыночному курсу.
currencystringобязательноКриптовалюта для получения. Одно из: "USDT", "ETH", "BTC", "SOL".
chainstringобязательноБлокчейн-сеть. Одно из: "trc20", "erc20", "btc", "sol". Должна быть совместима с выбранной валютой.
externalIdstringнеобязательноВаш внутренний идентификатор заказа. Возвращается без изменений в вебхуках. Должен быть уникальным для каждого мерчанта.
metadataobjectнеобязательноПроизвольный JSON-объект (макс. 2 КБ). Возвращается во всех вебхуках для этого заказа — удобно для передачи ID пользователей, ссылок на корзину и т. п.

Поддерживаемые сочетания валюта + сеть

currencychainСетьСреднее время подтверждения
USDTtrc20TRON (TRC-20)~1 мин
USDTerc20Ethereum (ERC-20)~2 мин
ETHerc20Ethereum~2 мин
BTCbtcBitcoin~30 мин
SOLsolSolana<5 сек

Ответ

201 Created
{
  "orderId":      "ord_a1b2c3d4e5f6g7h8",
  "payAddress":   "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "cryptoAmount": "29.99",
  "currency":     "USDT",
  "chain":        "trc20",
  "checkoutUrl":  "https://chainpay.pro/pay/ord_a1b2c3d4",
  "expiresAt":    "2026-03-22T09:00:00Z",
  "createdAt":    "2026-03-22T08:30:00Z"
}

Процесс оплаты

Как работает размещённая платёжная страница.

  1. 1
    ПеренаправлениеВаш сервер перенаправляет пользователя на checkoutUrl, который возвращается при создании заказа.
  2. 2
    Платёжная страницаРазмещённая страница показывает QR-код и адрес кошелька, заранее заполненный точной суммой в крипто. Пользователь сканирует QR-код или копирует адрес в приложение своего кошелька.
  3. 3
    ПодтверждениеChainPay отслеживает блокчейн. Как только достигнуто нужное число подтверждений, статус заказа меняется на confirming, затем на completed.
  4. 4
    Возврат на сайтПлатёжная страница показывает экран успеха. Если в панели настроен successUrl, пользователь автоматически перенаправляется туда.
  5. 5
    ВебхукВаш сервер получает вебхук payment.completed. Выполняйте заказ только после проверки подписи вебхука.
Срок действия: Заказы истекают через 30 минут после создания. Если в течение этого окна платёж не обнаружен, статус меняется на expired и отправляется вебхук payment.expired. Создайте новый заказ для повторной попытки.

Вебхуки

ChainPay отправляет подписанные HTTP POST-запросы на ваш URL вебхука при изменении статуса заказа.

Настройка

1

Перейдите в Панель → Приложения → Новое приложение

2

Укажите URL вебхука (например, https://yourapp.com/api/webhooks/chainpay)

3

Скопируйте сгенерированный секрет вебхука — используйте его для проверки подписей

События вебхуков

Поддерживаемые на данный момент события:

СобытиеКогда срабатывает
payment.completedЗаказ оплачен и подтверждён в сети
payment.expiredСрок заказа истёк без оплаты

Формат тела запроса

JSON
{
  "event": "payment.completed",
  "orderId": "ord_xxxxxxxx",
  "amount": "9.99",
  "currency": "USDT",
  "chain": "trc20",
  "txHash": "abc123...",
  "netAmount": "9.92",
  "completedAt": "2026-01-01T00:00:00.000Z",
  "metadata": {
    "userId": "your-user-id",
    "plan": "monthly"
  }
}

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

Каждый запрос вебхука содержит заголовок X-ChainPay-Signature. Проверяйте его с помощью HMAC-SHA256, используя секрет вебхука вашего приложения:

Node.js / TypeScript
import crypto from 'crypto'

function verifyWebhook(rawBody: string, signature: string, secret: string): boolean {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature)
  )
}

// In your webhook handler:
export async function POST(req: Request) {
  const rawBody = await req.text()
  const signature = req.headers.get('x-chainpay-signature') ?? ''

  if (!verifyWebhook(rawBody, signature, process.env.CHAINPAY_WEBHOOK_SECRET!)) {
    return new Response('Unauthorized', { status: 401 })
  }

  const event = JSON.parse(rawBody)
  if (event.event === 'payment.completed') {
    const { userId, plan } = event.metadata
    // activate user's plan
  }

  return new Response('OK')
}
Python
import hmac, hashlib

def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
    computed = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(computed, signature)

Протестируйте свой вебхук

1

Перейдите в Панель → Приложения → выберите своё приложение

2

Нажмите «Отправить тестовое событие»

3

Убедитесь, что ваш сервер получил запрос (ожидается HTTP 200)

Политика повторов

Неудачные доставки повторяются с экспоненциальной задержкой: 1 мин → 5 мин → 30 мин → 2 часа → 24 часа (всего 5 попыток).

После 5 неудачных попыток вебхук помечается как failed. Неудачные доставки смотрите в Панель → Оповещения.

Лучшие практики

  • Всегда проверяйте подпись перед обработкой
  • Быстро возвращайте HTTP 200 — тяжёлую обработку выполняйте асинхронно
  • Используйте orderId для дедупликации событий (вебхуки могут доставляться более одного раза)
  • Сохраняйте сырое тело запроса до парсинга, чтобы обеспечить точную проверку подписи

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

GEThttps://chainpay.pro/api/v1/orders/:id
Ответ
{
  "id":          "ord_a1b2c3d4e5f6g7h8",
  "amount":      "29.99",
  "cryptoAmount":"29.99",
  "netAmount":   "29.75",
  "currency":    "USDT",
  "chain":       "trc20",
  "status":      "completed",
  "payAddress":  "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "txHash":      "e3b0c44298fc1c149afbf4c8996fb92...",
  "externalId":  "order_abc123",
  "metadata":    { "userId": "user_456" },
  "createdAt":   "2026-03-22T08:30:00Z",
  "expiresAt":   "2026-03-22T09:00:00Z",
  "completedAt": "2026-03-22T08:45:00Z"
}

Значения статуса заказа

СтатусОписание
pendingЗаказ создан, ожидается отправка платежа пользователем.
confirmingТранзакция обнаружена в сети, ожидается достаточное число подтверждений блоков.
completedПлатёж полностью подтверждён. Можно безопасно выполнять заказ.
expiredПрошло 30 минут без обнаруженного платежа.
failedПроизошла непредвиденная ошибка. Обратитесь в поддержку, указав orderId.

API курсов

Получайте текущие курсы обмена к USD. API-ключ не требуется.

GEThttps://chainpay.pro/api/v1/rates
Ответ
{
  "USDT": 1.0,
  "ETH":  3450.00,
  "BTC":  87500.00,
  "SOL":  145.00,
  "updatedAt": "2026-03-22T08:00:00Z"
}

Курсы обновляются каждые 60 секунд на основе агрегированных рыночных данных. Параметр amount, передаваемый в эндпоинт создания заказа, всегда интерпретируется в USD; API конвертирует его в крипто по курсу, актуальному на момент создания заказа.

Режим песочницы

Протестируйте всю интеграцию без перемещения реальных средств.

Зарегистрируйтесь с ?mode=test, чтобы получить API-ключ sk_test_. Все стандартные эндпоинты работают в режиме песочницы одинаково — опрос блокчейна пропускается, а подтверждение вы запускаете вручную.

Шаг 1 — Получите API-ключ песочницы

cURL
curl -X POST "https://chainpay.pro/api/auth/register?mode=test" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "yourpassword"}'

# Response includes:
# { "merchant": { "apiKey": "sk_test_xxxxxxxxxxxxxxxx" } }

Шаг 2 — Создайте заказ с тестовым ключом

cURL
curl -X POST https://chainpay.pro/api/v1/orders \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10, "currency": "USDT", "chain": "trc20", "externalId": "test_order_1"}'

Шаг 3 — Симулируйте платёж

cURL
curl -X POST https://chainpay.pro/api/v1/sandbox/simulate-payment \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orderId": "ord_abc123"}'

# Response:
{
  "success":   true,
  "orderId":   "ord_abc123",
  "txHash":    "sandbox_ord_abc123_1711000000000",
  "netAmount": "9.92000000"
}
# The order status is now "completed" and your webhook is fired.
Хеши транзакций песочницы имеют префикс sandbox_. Эндпоинт симуляции платежа доступен только с ключами sk_test_. Попытка использовать его с боевым ключом возвращает 403.

Коды ошибок

Все ответы об ошибках используют единую JSON-структуру:

Структура ответа об ошибке
{
  "error": "INVALID_CHAIN",
  "message": "chain 'foo' is not supported for currency USDT",
  "status": 400
}
HTTP-статусРаспространённые коды ошибокПричина и решение
400INVALID_AMOUNT, INVALID_CURRENCY, INVALID_CHAIN, MISSING_FIELDТело запроса повреждено или отсутствует обязательное поле. Проверьте таблицу параметров запроса выше.
401UNAUTHORIZED, INVALID_API_KEYОтсутствует или недействителен заголовок Authorization. Убедитесь, что вы отправляете Bearer <key>.
403FORBIDDEN, SANDBOX_ONLYAPI-ключ не имеет прав на это действие (например, использование simulate-payment с боевым ключом).
404ORDER_NOT_FOUNDЗаказа с указанным ID не существует или он не принадлежит вашему аккаунту мерчанта.
429RATE_LIMITEDСлишком много запросов. Лимит по умолчанию — 60 запросов в минуту на API-ключ. Снизьте частоту и повторите после значения заголовка Retry-After.
500INTERNAL_ERRORНепредвиденная ошибка на стороне сервера. Повторите с экспоненциальной задержкой. Если ошибка повторяется, обратитесь в поддержку, указав ID запроса.

Выплаты

Как и когда ChainPay отправляет собранные средства на ваш кошелёк.

График выплат
Ежедневно в 02:00 UTC
Комиссия за обработку
0,8% за транзакцию
Минимальная выплата
Эквивалент $10

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

Совет: Комиссия за обработку удерживается с каждого заказа — netAmount в вебхуках уже отражает сумму после удержания комиссии. Выплата переводит сумму всех значений netAmount за день.

Готовы к интеграции?

Создайте аккаунт и получите API-ключ за считанные секунды.