Інтеграція криптоплатіжного шлюзу (CoinGate/NOWPayments/BitPay) на сайт

Інтеграція криптоплатіжного шлюзу (CoinGate/NOWPayments/BitPay) на сайт

Вступ

Інтегрували криптоплатіжний шлюз, але вебхуки не проходять, статуси зависають, а клієнти скаржаться на зниклі платежі? Типова причина — відсутність перевірки підпису сповіщень і неправильний маппінг статусів. Ми вирішуємо це за 1–3 дні: підключаємо CoinGate, NOWPayments або BitPay з повною обробкою вебхуків, часткових платежів і кастомними сторінками вибору монети. Використовуємо перевірені патерни: HMAC-верифікацію, черги для ретраїв, логування кожного IPN-запиту.

Які проблеми вирішуємо

• Верифікація вебхуків. Кожен провайдер використовує свій механізм підпису: HMAC-SHA512 (NOWPayments), токен (CoinGate), IPN-секрет (BitPay). Якщо пропустити перевірку — зловмисник може імітувати сповіщення та змінити статус замовлення. Ми завжди реалізуємо строгу перевірку підпису.
• Часткові платежі. NOWPayments вміє їх обробляти, але стандартних засобів доплати немає. Потрібно реалізувати логіку сповіщення та, за необхідності, повернення через API. На практиці 90% користувачів доплачують протягом години, якщо бачать зрозумілу інструкцію.
• Вибір монети. Покупець хоче платити своєю криптовалютою. Агрегатор пропонує сторінку вибору, але часто потрібна кастомна — вбудована в checkout сайту. Ми можемо створити таку сторінку з виведенням балансу та QR-коду.

Як ми це робимо

Використовуємо стек: PHP 8.3, Laravel 11, Guzzle. Клієнт для NOWPayments виглядає так:

use GuzzleHttp\Client;

class NOWPaymentsClient
{
    private Client $http;
    private string $apiKey;

    public function __construct(string $apiKey, bool $sandbox = false)
    {
        $this->apiKey = $apiKey;
        $baseUri = $sandbox ? 'https://api-sandbox.nowpayments.io/v1/' : 'https://api.nowpayments.io/v1/';
        $this->http = new Client([
            'base_uri' => $baseUri,
            'headers' => ['x-api-key' => $apiKey],
        ]);
    }

    public function createPayment(array $params): array
    {
        $response = $this->http->post('payment', ['json' => $params]);
        return json_decode($response->getBody()->getContents(), true);
    }

    public function getMinAmount(string $currency, string $fiatCurrency = 'usd'): float
    {
        $response = $this->http->get("min-amount?currency_from={$currency}&currency_to={$fiatCurrency}");
        return json_decode($response->getBody()->getContents(), true)['min_amount'];
    }
}

// Створення платежу
$client = new NOWPaymentsClient(env('NOWPAYMENTS_API_KEY'), app()->isLocal());
$payment = $client->createPayment([
    'price_amount' => $order->total,
    'price_currency' => 'usd',
    'pay_currency' => 'btc', // або 'eth', 'usdttrc20', тощо.
    'order_id' => (string) $order->id,
    'order_description'=> 'Замовлення #' . $order->id,
    'ipn_callback_url' => route('payments.nowpayments.webhook'),
    'success_url' => route('orders.success', $order),
    'cancel_url' => route('checkout'),
]);

Редирект покупця на $payment['invoice_url']. NOWPayments показує сторінку вибору монети та QR-код з адресою для оплати.

CoinGate: API

$payment = $coingate->order->create([
    'order_id' => $order->id,
    'price_amount' => $order->total,
    'price_currency' => 'EUR',
    'receive_currency' => 'EUR', // отримувати в євро, не в крипті
    'title' => 'Замовлення #' . $order->id,
    'description' => implode(', ', $order->itemNames()),
    'callback_url' => route('payments.coingate.webhook'),
    'success_url' => route('orders.success', $order),
    'cancel_url' => route('checkout'),
    'token' => $order->token, // унікальний токен для безпеки
]);

// Редирект на $payment->payment_url

Обробка webhook — NOWPayments

NOWPayments надсилає IPN на ipn_callback_url:

public function handleNowPaymentsWebhook(Request $request): Response
{
    $raw = $request->getContent();
    $signature = $request->header('x-nowpayments-sig');

    // Верифікація підпису
    $sorted = json_encode(
        collect(json_decode($raw, true))->sortKeys()->all(),
        JSON_UNESCAPED_UNICODE
    );
    $expected = hash_hmac('sha512', $sorted, config('services.nowpayments.ipn_secret'));

    if (!hash_equals($expected, $signature)) {
        return response('Forbidden', 403);
    }

    $data = json_decode($raw, true);
    $order = Order::find($data['order_id']);

    $statusMap = [
        'waiting' => 'pending',
        'confirming' => 'pending',
        'confirmed' => 'paid',
        'sending' => 'paid',
        'partially_paid' => 'partially_paid',
        'finished' => 'paid',
        'failed' => 'failed',
        'refunded' => 'refunded',
        'expired' => 'expired',
    ];

    $order->update(['payment_status' => $statusMap[$data['payment_status']] ?? 'unknown']);

    if ($data['payment_status'] === 'finished') {
        $order->markAsPaid($data['payment_id']);
        event(new OrderPaid($order));
    }

    return response('OK', 200);
}

Webhook — CoinGate

CoinGate надсилає form-encoded POST з полем token для верифікації:

public function handleCoingateWebhook(Request $request): Response
{
    $token = $request->input('token');
    $orderId = $request->input('order_id');
    $status = $request->input('status');
    $order = Order::find($orderId);

    if (!$order || $order->payment_token !== $token) {
        return response('Forbidden', 403);
    }

    match ($status) {
        'paid' => $order->markAsPaid($request->input('id')),
        'canceled' => $order->update(['payment_status' => 'cancelled']),
        'expired' => $order->update(['payment_status' => 'expired']),
        default => null,
    };

    return response('OK', 200);
}

Вибір криптовалюти покупцем

Більшість агрегаторів показують власну сторінку вибору монети. Якщо потрібна кастомна сторінка вибору на своєму сайті — створіть окремий invoice для кожної монети або отримайте список підтримуваних монет через API і створюйте invoice тільки при виборі:

// NOWPayments: отримати список монет
$currencies = $client->getAvailableCurrencies();
// Показати користувачеві випадаючий список
// При виборі — створити payment з обраною pay_currency

Часткові платежі

NOWPayments підтримує статус partially_paid — користувач заплатив менше, ніж потрібно. Стандартний сценарій: повідомити користувача та запропонувати доплатити або повернути. Автоматичне повернення через API NOWPayments — доступне через refunds endpoint, але тільки в крипті.

Як забезпечити безпеку вебхуків?

Перевірка підпису — обов'язковий мінімум. Додатково ми використовуємо блокування за IP та логування кожного запиту. NOWPayments публікує список своїх IP-адрес, CoinGate рекомендує перевіряти токен. BitPay підтримує IPN-секрет. Ми документуємо кожен крок, щоб ви могли відтворити перевірку.

Чому NOWPayments вигідніший за CoinGate у 2 рази?

Порівняйте комісії: NOWPayments — 0,5%, CoinGate — 1%. Крім того, NOWPayments не вимагає верифікації для фізичних осіб, що прискорює запуск.

Як обробляти часткові платежі?

Якщо користувач відправив менше, ніж потрібно, NOWPayments змінює статус на partially_paid. Ми рекомендуємо:

• Створити сповіщення (email/telegram) із сумою недостачі.
• Дати посилання на повторний рахунок (новий payment з pay_amount = недостача).
• Якщо доплата не надійшла за 24 години — автоматично повернути кошти через API (якщо провайдер дозволяє).

Наш досвід показує, що 90% користувачів доплачують протягом години, якщо бачать зрозумілу інструкцію.

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

• Аудит поточної платіжної системи та вимог
• Налаштування облікового запису провайдера (верифікація, ключі, IPN-секрети)
• Розробка клієнта для API (на PHP/Laravel або іншому стеку)
• Реалізація вебхуків з перевіркою підпису та маппінгом статусів
• Обробка часткових платежів (сповіщення, доплата, повернення)
• Кастомна сторінка вибору монети (опціонально)
• Документація схеми платежів
• Тестування в пісочниці та бойовому режимі
• Навчання команди роботі з панеллю провайдера
• Гарантія на код — 30 днів підтримки

Процес роботи

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