Интеграция с 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. Это ключевое поле для reconciliation.

Обработка callback (webhook)

CoinGate шлёт POST-запрос на callback_url при каждом изменении статуса заказа. Обязательна верификация подлинности запроса:

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 — стандартная практика.

Статусы заказа

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

Underpayment: пользователь заплатил меньше из-за комиссий за перевод. 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 окружение