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

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

Вибір CoinPayments для криптоплатежів

CoinPayments підтримує понад 2000 монет і токенів, включаючи Bitcoin, Ethereum, USDT, Solana та інші. Це один із найстаріших процесорів, що підтверджує його надійність. Інтеграція потребує глибокого розуміння протоколу: HMAC-підписи, IPN-верифікація, обробка статусів. Ми беремо це на себе. Порівняння з іншими шлюзами: CoinPayments пропонує в 5 разів більше монет, ніж NextPay, і вдвічі нижчу середню комісію простою (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.
• Налаштування доступів та безпечне зберігання ключів.
• Навчання команди обробці статусів.
• Підтримка протягом місяця після запуску.

Замовте інтеграцію з гарантією стабільної роботи. Отримайте консультацію інженера — це безкоштовно.