Інтеграція з CoinGate

Інтеграція з CoinGate

CoinGate — payment processor, який бере на себе складність роботи з множиною блокчейнів: прийняття BTC, ETH, LTC, USDT та ~70 інших монет, конвертація в EUR/USD, виплати на банківський рахунок або крипто-гаманець. Ви не займаєтесь управлінням ключами і моніторингом блокчейнів — CoinGate робить це за вас в обмін на комісію (1% від транзакції).

Інтеграція технічно проста, але є кілька місць, де легко помилитись.

API інтеграція

CoinGate надає REST API v2. Аутентифікація — Bearer токен у заголовку. Тестове оточення: https://api-sandbox.coingate.com, production: https://api.coingate.com.

Створення замовлення

const axios = require('axios')

const COINGATE_TOKEN = process.env.COINGATE_API_TOKEN

async function createCryptoOrder(params) {
  const { orderId, amount, currency, callbackUrl, successUrl, cancelUrl } = params
  
  const response = await axios.post(
    'https://api.coingate.com/v2/orders',
    {
      order_id: orderId,           // ваш внутрішній ID
      price_amount: amount,        // сума в price_currency
      price_currency: currency,    // EUR, USD, BTC та ін.
      receive_currency: 'EUR',     // у чому отримати виплату
      callback_url: callbackUrl,   // webhook для уведомлень
      success_url: successUrl,     // редирект після оплати
      cancel_url: cancelUrl,
      title: `Order #${orderId}`,
      description: 'Payment for services'
    },
    {
      headers: {
        'Authorization': `Token ${COINGATE_TOKEN}`,
        'Content-Type': 'application/json'
      }
    }
  )
  
  return {
    coingate_id: response.data.id,
    payment_url: response.data.payment_url,  // URL куди редиректити користувача
    status: response.data.status
  }
}

Поле order_id — ваш внутрішній ідентифікатор, він повернеться в callback. Це ключове поле для согласованості.

Обробка callback (webhook)

CoinGate шле POST-запит на callback_url при кожній зміні статусу замовлення. Верифікація автентичності webhook обов'язкова:

app.post('/webhooks/coingate', express.urlencoded({ extended: true }), async (req, res) => {
  // CoinGate шле form-encoded дані, не JSON
  const {
    id,           // CoinGate order ID
    order_id,     // ваш внутрішній ID
    status,       // pending, confirming, paid, invalid, expired, canceled, refunded
    price_amount,
    price_currency,
    receive_currency,
    receive_amount,
    pay_amount,   // скільки крипти отримано
    pay_currency  // якою монетою заплатив користувач
  } = req.body
  
  // Верифікація через повторний запит до API (немає підпису у CoinGate в стандартному API)
  const verified = await verifyCoinGateOrder(id, order_id)
  if (!verified) {
    return res.status(400).send('Verification failed')
  }
  
  switch (status) {
    case 'paid':
      await markOrderPaid(order_id, { pay_currency, pay_amount })
      break
    case 'invalid':
      // неправильна сума або інша проблема — потребує ручної обробки
      await flagOrderForReview(order_id)
      break
    case 'expired':
      await cancelOrder(order_id)
      break
  }
  
  res.sendStatus(200)  // завжди відповідаємо 200, інакше CoinGate буде повторювати
})

async function verifyCoinGateOrder(coingateId, internalOrderId) {
  const response = await axios.get(
    `https://api.coingate.com/v2/orders/${coingateId}`,
    { headers: { 'Authorization': `Token ${COINGATE_TOKEN}` } }
  )
  return response.data.order_id === internalOrderId
}

Важливо: CoinGate не додає HMAC-підпис до callback за замовчуванням. Верифікація через додатковий GET-запит до API — стандартна практика.

Статуси замовлення

Типові проблеми

Недоплата: користувач заплатив менше через комісії за переказ. CoinGate переводить замовлення в invalid. Рішення: в настройках CoinGate можна включити tolerance margin (зазвичай 1–2%).

Затримка callback: CoinGate іноді затримує callback при нагрузці. Рекомендується: додатково поллити статус замовлення кожні 30–60 секунд для замовлень у стані confirming.

Тестування: у sandbox оточенні використовуйте тестові ключі і тестові монети. Sandbox імітує реальні затримки підтверджень — тести з миттєвим paid потрібно робити через прямий виклик API sandbox з форсованим статусом.

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

• Реєстрація і настройка аккаунту CoinGate (настройка receive currency, KYC документація)
• Реалізація API клієнта з створенням замовлень
• Webhook endpoint з верифікацією і обробкою всіх статусів
• Інтеграція з існуючою системою замовлень
• Тестування через sandbox оточення