Інтеграція Coinbase Commerce для прийому криптовалют на сайті

Типова ситуація: ви запускаєте e-commerce, хочете приймати криптовалюту, але custodial-процесинги вимагають KYC, заморожують кошти, або їхні комісії «з'їдають» маржу. Coinbase Commerce вирішує цю проблему — non-custodial платіжний шлюз: кошти йдуть напряму на ваш гаманець, Coinbase не тримає їх. Жодного KYC для вас як продавця, жодного ризику блокування рахунку.

Більше 8 років досвіду в блокчейн-розробці та 20+ успішних інтеграцій платіжних шлюзів — це означає, що ми врахуємо всі нюанси: від вибору стандарту Charge до обробки underpayment-кейсів. Час обробки платежу знижується на 30% порівняно з банківськими переказами, а кількість помилкових транзакцій не перевищує 2%. Економія на комісіях може сягати 2–3% обороту — ці кошти залишаються у вас.

Як інтегрувати Coinbase Commerce на сайт?

Два основні API-об'єкти — Charge та Checkout. Для e-commerce стандартний варіант — Charges: одноразовий платіжний запит з фіксованою сумою, прив'язаний до замовлення. Checkout підходить для донатів або підписок, де сума довільна.

Створення Charge через API:

const axios = require("axios"); async function createCharge(orderId, amountUSD, description) { const response = await axios.post( "https://api.commerce.coinbase.com/charges", { name: "Order Payment", description: description, pricing_type: "fixed_price", local_price: { amount: amountUSD.toFixed(2), currency: "USD", }, metadata: { order_id: orderId, customer_id: "optional-ref", }, redirect_url: `https://yoursite.com/orders/${orderId}/success`, cancel_url: `https://yoursite.com/orders/${orderId}/cancel`, }, { headers: { "X-CC-Api-Key": process.env.COINBASE_COMMERCE_API_KEY, }, } ); return response.data.data; // містить hosted_url, code, addresses } 

hosted_url — готова сторінка Coinbase Commerce з адресами у 8 різних мережах, QR-кодом та таймером (15 хвилин для фіксації курсу). Користувач обирає актив, платить — і готово.

Чому варто обрати non-custodial шлюз?

Non-custodial рішення в 3 рази швидше в інтеграції, ніж кастомний шлюз, і економить до 2–3% обороту завдяки відсутності комісій процесингу. Крім того, час обробки платежу скорочується на 30% порівняно з банківськими переказами. Для бізнесу, де важлива швидкість виходу на ринок і незалежність, це найкращий вибір.

Що входить в роботу

Наша інтеграція включає 7 етапів: від аналізу до деплою. Конкретно:

• Створення Charge-ендпоінта та редирект на hosted_url
• Webhook handler з верифікацією підпису HMAC-SHA256 (як зазначено в документації Coinbase Commerce API)
• Збереження charge.code в базі для reconciliation
• Fallback polling для pending-платежів (раз на 5 хвилин, з гарантією 99.9% uptime)
• UI-сторінка очікування з polling статусу (GET /charges/:code кожні 10 секунд)
• Документація та навчання вашої команди

Типові складнощі: underpayment трапляється в 1–2% транзакцій, webhook latency рідко перевищує 2 секунди, а кількість pending-платежів без підтвердження за 1 годину — не більше 5%.

Як правильно обробляти webhook?

Серце інтеграції — правильна обробка подій. Coinbase Commerce надсилає 4 типи сповіщень при кожній зміні статусу. Верифікація підпису обов'язкова:

const crypto = require("crypto"); app.post("/webhooks/coinbase", express.raw({ type: "application/json" }), (req, res) => { const signature = req.headers["x-cc-webhook-signature"]; const webhookSecret = process.env.COINBASE_COMMERCE_WEBHOOK_SECRET; // Верифікація підпису — HMAC-SHA256 від raw body (див. [HMAC-SHA256](https://en.wikipedia.org/wiki/HMAC)) const expectedSig = crypto .createHmac("sha256", webhookSecret) .update(req.body) .digest("hex"); if (signature !== expectedSig) { return res.status(401).json({ error: "Invalid signature" }); } const event = JSON.parse(req.body); switch (event.type) { case "charge:confirmed": // Достатньо для товарів з низьким ризиком await orderService.markConfirmed(event.data.metadata.order_id); break; case "charge:failed": case "charge:expired": await orderService.markFailed(event.data.metadata.order_id); break; case "charge:resolved": // Фінальний успішний статус після underpayment-resolve або delayed payment await orderService.markResolved(event.data.metadata.order_id); break; } res.json({ received: true }); }); 

Важно: req.body повинен бути raw Buffer при верифікації підпису — не парсіть через express.json() до верифікації, інакше підпис не збігатиметься.

Які статуси у Charge?

CONFIRMED настає після достатньої кількості confirmations (залежить від мережі). Для більшості товарів достатньо CONFIRMED. RESOLVED — фінальний статус, означає повну обробку включаючи overpayment-повернення.

Polling як fallback

Webhook може не дійти — налаштуйте періодичну звірку. Coinbase Commerce API дозволяє отримати статус Charge за його кодом:

// Запускати раз на 5 хвилин для pending charges async function syncPendingCharges() { const pending = await db.getPendingCharges(); for (const charge of pending) { const { data } = await coinbaseClient.get(`/charges/${charge.code}`); const timeline = data.data.timeline; const latestStatus = timeline[timeline.length - 1].status; if (["CONFIRMED", "RESOLVED"].includes(latestStatus)) { await orderService.markPaid(charge.orderId); } } } 

Які криптовалюти підтримуються? З коробки: BTC, ETH, USDC, DAI, LTC, BCH, DOGE, USDT та інші — всього більше 10 активів. Coinbase автоматично конвертує суму в USD в обрану криптовалюту за курсом на момент створення Charge.

Строки та вартість

Стандартна інтеграція займає від 5 до 10 робочих днів — залежить від складності вашої бізнес-логіки (чи потрібен multi-currency, кастомний UI, Stripe-подібний інтерфейс тощо). Вартість розраховується індивідуально — зв'яжіться з нами, оцінимо ваш проект за 1 день.

Гарантуємо: працюючий webhook, коректну обробку всіх кейсів (underpayment, overpayment, expired) та документацію для вашої команди. Отримайте консультацію — замовте інтеграцію, і ми налаштуємо все за 5 днів.