Crypto Payment Gateway API: Полное руководство по интеграции для 2026

Crypto payment gateway API — это программный интерфейс, позволяющий вашему приложению создавать платёжные запросы, отслеживать подтверждения транзакций в блокчейне и производить расчёты без непосредственного управления кошельками или приватными ключами. Вы вызываете REST-эндпоинт, шлюз обрабатывает блокчейн-уровень, а ваш бэкенд получает вебхук, когда платёж поступает.

Это отличается от платёжного процессора (обрабатывает фиатную авторизацию) или кошелька с самостоятельным хранением (где пользователи сами подписывают транзакции). API стоит посередине: ваше приложение управляет UX, шлюз обрабатывает подтверждения, проверки соответствия и опциональную конвертацию в фиат.

В платёжном цикле crypto payment gateway выполняет четыре функции: генерирует адрес депозита или платёжный URL, отслеживает блокчейн на входящие средства, отправляет вебхук при достижении порога подтверждений и опционально конвертирует полученную сумму. Ваша интеграция должна обрабатывать лишь шаги 1 и 3.

Полный платёжный процесс состоит из пяти шагов.

Шаг 1 — Создание платёжного намерения

Ваш сервер вызывает `POST /payments` с ожидаемой суммой, валютой и сгенерированным вами `orderId`. Шлюз возвращает `paymentId`, адрес депозита и метку времени истечения.

Шаг 2 — Перенаправление или отображение

Для hosted checkout вы перенаправляете пользователя на URL шлюза. Для прямых интеграций — отображаете адрес депозита и QR-код в своём UI.

Шаг 3 — Получение вебхук-коллбэка

Когда шлюз обнаруживает входящую транзакцию, он отправляет POST-запрос на ваш вебхук-адрес. Payload содержит `paymentId`, текущий статус, количество подтверждений и полученную сумму.

Шаг 4 — Верификация и подтверждение

Перед любыми действиями проверьте HMAC-подпись в заголовках запроса. Если он не совпадает — отклоните запрос. Затем вызовите `GET /payments/{id}` для проверки канонического статуса на стороне сервера.

Шаг 5 — Выполнение заказа

Когда серверный статус подтверждён как `completed` — выполняйте заказ идемпотентно, используя `paymentId` как ключ. Вебхуки могут приходить несколько раз для одного и того же события.

Конфигурация crypto payment gateway определяет синхронный или асинхронный режим расчётов.

Хорошо спроектированный payment gateway API предоставляет четыре группы основных эндпоинтов.

Создание платёжного намерения — POST /payments

Минимальный запрос выглядит так:

```json

{

"orderId": "ord_abc123",

"amount": "250.00",

"currency": "USD",

"payCurrency": "ETH",

"callbackUrl": "https://yourapp.com/webhooks/payments",

"successUrl": "https://yourapp.com/orders/ord_abc123/success",

"expiresIn": 1800

}

```

Ответ содержит `paymentId`, `depositAddress`, `expectedAmount` в крипте и `expiresAt`.

Статус транзакции — GET /payments/{id}

Используйте этот эндпоинт для подтверждения статуса после получения вебхука.

Возврат средств — POST /refunds

Передайте `paymentId` и `amount`. Шлюз инициирует on-chain перевод обратно на адрес отправителя.

Отчёты о расчётах — GET /settlements

Запрашивайте расчёты по диапазону дат для reconciliation.

Вебхуки лучше опроса по одной причине: вы узнаёте о подтверждениях сразу, а не на следующем цикле опроса.

Почему вебхуки лучше опроса

Опрос генерирует лишние API-вызовы, расходует лимит запросов и увеличивает задержку. Вебхуки отправляют события в момент достижения порога подтверждений.

HMAC-SHA256 Верификация подписи

```javascript

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signature, secret) {

const expectedSig = crypto

.createHmac('sha256', secret)

.update(rawBody, 'utf8')

.digest('hex');

const expected = Buffer.from(expectedSig, 'hex');

const received = Buffer.from(signature, 'hex');

if (expected.length !== received.length) return false;

return crypto.timingSafeEqual(expected, received);

}

app.post('/webhooks/payments', express.raw({ type: 'application/json' }), (req, res) => {

const sig = req.headers['x-signature'];

if (!verifyWebhookSignature(req.body, sig, process.env.WEBHOOK_SECRET)) {

return res.status(401).json({ error: 'Invalid signature' });

}

const event = JSON.parse(req.body);

res.json({ received: true });

});

```

Передавайте raw body (Buffer), а не разобранный JSON.

Повтор с экспоненциальным backoff

Шлюзы повторяют неудачные вебхуки — обычно 3-5 раз с экспоненциальным backoff.

Ключи идемпотентности

Используйте `paymentId` как ключ идемпотентности для предотвращения дублирования заказов.

Большинство крупных шлюзов поставляют SDK для TypeScript/Node, Python, Go и PHP.

Используйте SDK когда:

• •Ваш стек соответствует поддерживаемому языку
• •Нужна типобезопасность объектов запросов/ответов
• •Вам нужна встроенная логика повтора

Используйте Raw REST когда:

• •Ваш стек не поддерживается (Rust, Elixir)
• •Нужен точный контроль над HTTP-поведением
• •Версия SDK отстаёт от версии API

Для большинства команд SDK — правильный выбор. Узнайте больше о том, что blockchain APIs для разработчиков делают под капотом.

Реалистичное пошаговое руководство по интеграции.

Шаг 1: Выбор провайдера Payment Gateway API

Оценка включает пять критериев: поддерживаемые блокчейны, структура комиссий, качество sandbox, глубина документации и готовность к соответствию (KYC/AML встроенный или ваша ответственность).

Для бизнесов с DeFi-требованиями также проверяйте совместимость с DeFi платформами.

Шаг 2: Получение API-ключей и доступа к Sandbox

Ваш набор API-ключей состоит из публичного ключа (в заголовках запросов) и секретного ключа (для HMAC-подписания). Храните оба в переменных среды.

Шаг 3: Создание первого платёжного намерения

```javascript

const axios = require('axios');

async function createPayment(orderId, amountUSD) {

const response = await axios.post(

'https://api.yourgateway.com/v1/payments',

{

orderId,

amount: amountUSD.toString(),

currency: 'USD',

payCurrency: 'USDT_ETH',

callbackUrl: process.env.WEBHOOK_URL,

expiresIn: 3600,

},

{

headers: {

Authorization: `Bearer ${process.env.GATEWAY_API_KEY}`,

'Idempotency-Key': orderId,

'Content-Type': 'application/json',

},

}

);

return response.data;

}

```

Шаг 4: Обработка вебхук-коллбэков

Настройте вебхук-эндпоинт перед тестированием. В sandbox большинство шлюзов позволяют вручную триггерить вебхук-события — тестируйте каждый переход статуса.

Шаг 5: Верификация и выполнение заказа

После получения вебхука `completed` всегда выполняйте серверную верификацию (`GET /payments/{id}`). Затем выполняйте заказ и помечайте его обработанным с `paymentId` в качестве ключа идемпотентности.

Безопасность — не вопрос после запуска. Эти требования относятся к стадии архитектурных решений.

Безопасность транспорта

Минимум TLS 1.3 для всего API-взаимодействия.

Управление API-ключами

Ротируйте API-ключи ежеквартально. Используйте отдельные пары ключей для sandbox и production.

Соответствие KYC/AML

Для бизнесов, обрабатывающих выше определённых порогов, применяются рекомендации FATF по AML. Стандарты PCI DSS технически применяются к крипто-платёжным потокам.

Подписанные запросы

Некоторые провайдеры требуют подписанных API-запросов (аналог AWS Signature V4). Для бизнесов, создающих полноценные финтех-решения, обязателен архитектурный обзор безопасности API перед запуском.

Вот как основные провайдеры сравниваются по критериям, важным для принятия решений об интеграции.

Это ошибки, которые команды делают в продакшне, а не в туториалах.

Неправильные пороговые значения подтверждений

Bitcoin требует 6 подтверждений для транзакций с большими суммами — около 60 минут. Использование 1 подтверждения открывает вас для атак двойного расходования. Устанавливайте пороги в зависимости от суммы: 1 для <$100, 3 для $100-$1000, 6 для >$1000 в Bitcoin mainnet.

Обработка on-chain таймаутов

Крипто-транзакции могут оставаться неподтверждёнными часами. Держите состояние `watchAddress` активным 24-72 часа после истечения платёжного намерения.

Ошибки оценки газа

Для EVM-блокчейнов добавьте буфер толерантности 5-10% для ETH-деноминированных платежей или переходите на стейблкоины USDT/USDC.

Узнайте больше о полной стоимости разработки в статье о разработке crypto payment gateway.