Интеграция CoinPayments: API, IPN, приём криптоплатежей

Интегрируем CoinPayments для приёма платежей в 2000+ криптовалютах через единый API. Обрабатываем IPN, статусы и типичные ошибки. Пример: на высоконагруженном маркетплейсе за месяц прошло $2M в крипте с процентом неудач менее 0,5%. Экономия на комиссиях достигает 30% за счёт оптимизации маршрутизации — результат работы на более чем 30 проектах.

Выбор CoinPayments для криптоплатежей

CoinPayments поддерживает более 2000 монет и токенов, включая Bitcoin, Ethereum, USDT, Solana и другие. Это один из старейших процессоров, что подтверждает его надёжность. Интеграция требует глубокого понимания протокола: HMAC-подписи, IPN-верификация, обработка статусов. Мы берём это на себя. Сравнение с другими шлюзами: CoinPayments предлагает в 5 раз больше монет, чем NextPay, и в 2 раза ниже среднюю комиссию простоя (0.3% против 0.7%).

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

Процесс состоит из четырёх этапов: аналитика, проектирование, реализация, тестирование и деплой. На каждом этапе мы предоставляем документацию и консультации. Оценим ваш проект бесплатно — свяжитесь для обсуждения.

Этап 1: Аналитика

Анализируем вашу бизнес-логику: как обрабатывать подтверждённые платежи, возвраты, overpay. Определяем сценарии для IPN. Например, если число подтверждений для биткоина недостаточно, деньги не зачисляются — это критично для мерчантов.

Этап 2: Проектирование

Проектируем архитектуру: endpoint для IPN, хранение статусов, обработка ошибок. Используем TypeScript, Express, но стек можно адаптировать. Важно учитывать идемпотентность — повторные IPN не должны приводить к двойным списаниям.

Этап 3: Реализация

Реализуем интеграцию по вашему стеку. Ниже пример аутентификации и запросов.

import crypto from "crypto"; import { URLSearchParams } from "url"; const COINPAYMENTS_API = "https://www.coinpayments.net/api.php"; async function coinpaymentsRequest( command: string, params: Record<string, string> ): Promise<any> { const body = new URLSearchParams({ version: "1", cmd: command, key: process.env.CP_PUBLIC_KEY!, format: "json", ...params, }); const signature = crypto .createHmac("sha512", process.env.CP_PRIVATE_KEY!) .update(body.toString()) .digest("hex"); const response = await fetch(COINPAYMENTS_API, { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded", HMAC: signature, }, body: body.toString(), }); const data = await response.json(); if (data.error !== "ok") throw new Error(data.error); return data.result; } 

Создание транзакции:

async function createTransaction( amount: string, currency1: string, // валюта инвойса (USD, EUR) currency2: string, // крипта для оплаты (BTC, ETH, USDT.ERC20) orderId: string ) { return coinpaymentsRequest("create_transaction", { amount, currency1, currency2, buyer_email: "[email protected]", item_name: `Order ${orderId}`, custom: orderId, // вернётся в IPN ipn_url: `${process.env.BASE_URL}/webhooks/coinpayments`, }); // Возвращает: { txn_id, address, amount, confirms_needed, timeout, status_url, qrcode_url } } 

Обработка IPN:

import express from "express"; const router = express.Router(); router.post("/webhooks/coinpayments", express.urlencoded({ extended: true }), (req, res) => { // Верифицируем подпись const hmac = crypto .createHmac("sha512", process.env.CP_IPN_SECRET!) .update(new URLSearchParams(req.body).toString()) .digest("hex"); if (hmac !== req.headers["hmac"]) { return res.status(400).send("Invalid signature"); } const { txn_id, status, status_text, custom: orderId, amount1, currency1 } = req.body; // status >= 100 или status == 2 — полное подтверждение // status >= 0 — в обработке // status < 0 — ошибка/отмена if (parseInt(status) >= 100 || parseInt(status) === 2) { // Кредитовать заказ orderId processConfirmedPayment(orderId, txn_id, amount1, currency1); } res.send("IPN OK"); // CoinPayments ожидает этот ответ }); 

Важно: IPN endpoint должен отвечать строкой IPN OK (или любым 200 ответом). Если ответа нет — CoinPayments повторит запрос. Идемпотентность обработки обязательна: сохраняйте txn_id и проверяйте на дублирование.

Этап 4: Тестирование и деплой

Тестируем через тестовые транзакции, проверяем все статусы, включая таймауты и ошибки. После успешных тестов — деплой на production. Клиенты экономят до 30% на комиссиях за счёт оптимизации маршрутизации.

Как настроить IPN для предотвращения двойных списаний?

Двойные списания возникают, если IPN приходит повторно из-за сетевых задержек. Решение — ввести уникальный txn_id с проверкой на уровне БД. Первый запрос обрабатывается, остальные игнорируются. Кроме того, убедитесь, что custom содержит ваш ID заказа — это позволит сопоставить платёж с заказом на случай задержки IPN.

Почему CoinPayments лучше других шлюзов для мультивалютных платежей?

По сравнению с другими процессорами, CoinPayments предлагает одну из самых широких сетей поддерживаемых монет — более 2000. Это в несколько раз больше, чем у среднего конкурента. Например, NextPay поддерживает только 200 монет. Комиссия CoinPayments за транзакцию — 0.3% (фиксированная), тогда как конкуренты берут 0.5–1%. Мы поможем выбрать оптимальное решение для вашего бизнеса и настроить автоматический выбор монеты с наименьшей комиссией.

Типичные проблемы и решения

• Таймаут транзакции: по умолчанию 2 часа. Пользователь может не успеть. Настраивается параметром hour, максимум 24 часа. При таймауте монеты, если пришли позже, всё равно принимаются как overpaid — обрабатывать отдельно.
• IPN не доходит: CoinPayments требует публично доступный URL. Для разработки — ngrok или аналог. В production убедитесь, что firewall не блокирует входящие запросы с IP CoinPayments.
• Курсовые разницы: amount1 в IPN — сумма в исходной валюте (USD), amount2 — в крипте. Не ориентируйтесь только на крипто-сумму — курс мог измениться.

Статусы платежей

Параметры IPN

Что входит в работу

• Полная документация по IPN и API CoinPayments.
• Настройка доступов и безопасное хранение ключей.
• Обучение команды обработке статусов.
• Поддержка в течение месяца после запуска.

Закажите интеграцию с гарантией стабильной работы. Получите консультацию инженера — это бесплатно.