Інтеграція платіжної системи iPay на сайт

Інтеграція платіїної системи iPay на сайт

iPay — український платіжний сервіс, орієнтований на малий та середній бізнес. Підтримує карти Visa, Mastercard, оплату через Приват24, а також токенізацію для повторних списань. Документація доступна на сайті ipay.ua, API — REST з JSON.

Реєстрація та отримання ключів

Після реєстрації у системі iPay та верифікації бізнесу видаються:

• salt — сіль для підпису
• sign_key — ключ підпису
• merchant_id (mch_id) — ідентифікатор магазину

Тестовий режим активується параметром s_cost=1 при тестових транзакціях.

Створення транзакції

function createIPayTransaction(int $orderId, float $amount, string $description): array
{
    $mchId   = env('IPAY_MERCHANT_ID');
    $salt    = env('IPAY_SALT');
    $signKey = env('IPAY_SIGN_KEY');

    // Підпис: HMAC-SHA512 від конкатенації параметрів
    $body = [
        'auth' => [
            'mch_id'   => $mchId,
            'salt'     => $salt,
            'sign'     => '', // буде замінено
        ],
        'transaction' => [
            'mch_id'           => $mchId,
            'srv_id'           => 1, // ID послуги з ЛК
            's_amount'         => $amount,
            's_currency_iso'   => 'UAH',
            'dsc'              => $description,
            'ext_trn_id'       => (string)$orderId,
            'response_url'     => 'https://example.com/webhook/ipay',
            'redirect_url'     => 'https://example.com/payment/return',
            'lang'             => 'ru',
        ],
    ];

    $signData = $body['transaction'];
    ksort($signData);
    $signString = implode(';', array_values($signData));
    $body['auth']['sign'] = hash_hmac('sha512', $signString, $signKey);

    $response = Http::post('https://api.ipay.ua/api/v1/transactions', $body);
    return $response->json();
}

// Використання:
$result = createIPayTransaction(12345, 1500.00, 'Заказ #12345');
$paymentUrl = $result['url']; // редирект покупця

Обробка сповіщення

public function webhook(Request $request): JsonResponse
{
    $data = $request->json()->all();

    // Перевіряємо підпис відповіді
    $receivedSign = $data['auth']['sign'] ?? '';
    $transaction  = $data['transaction'];
    ksort($transaction);
    $expectedSign = hash_hmac('sha512', implode(';', array_values($transaction)), env('IPAY_SIGN_KEY'));

    if (!hash_equals($expectedSign, $receivedSign)) {
        return response()->json(['error' => 'invalid sign'], 403);
    }

    $status = $data['transaction']['status'];
    $extId  = $data['transaction']['ext_trn_id']; // наш order ID

    if ($status === 'SUCCESS') {
        Order::where('id', $extId)->update([
            'status'         => 'paid',
            'transaction_id' => $data['transaction']['id'],
        ]);
    }

    return response()->json(['ok' => true]);
}

Статуси транзакції: SUCCESS, FAILURE, PROCESSING, REFUNDED.

Перевірка статусу транзакції

Додатково до webhook — перевірка статусу за запитом на сторінці return:

public function return(Request $request): View
{
    $extTrnId = $request->input('ext_trn_id');

    $body = [
        'auth' => [
            'mch_id' => env('IPAY_MERCHANT_ID'),
            'salt'   => env('IPAY_SALT'),
            'sign'   => hash_hmac('sha512', $extTrnId, env('IPAY_SIGN_KEY')),
        ],
        'request' => ['ext_trn_id' => $extTrnId],
    ];

    $response = Http::post('https://api.ipay.ua/api/v1/transactions/info', $body);
    $status = $response->json('transaction.status');

    $order = Order::where('id', $extTrnId)->firstOrFail();
    return view('payment.result', ['paid' => $status === 'SUCCESS', 'order' => $order]);
}

Токенізація

iPay підтримує збереження карти для подальших списань. Після першого платежу у даних транзакції повертається card_token. Для повторного списання:

$body = [
    'auth' => [...],
    'transaction' => [
        'mch_id'     => env('IPAY_MERCHANT_ID'),
        'srv_id'     => 1,
        's_amount'   => 500.00,
        's_currency_iso' => 'UAH',
        'card_token' => $savedToken,
        'ext_trn_id' => 'order-12346',
        'dsc'        => 'Повторне списання',
    ],
];
Http::post('https://api.ipay.ua/api/v1/transactions/token', $body);

Повернення

$body = [
    'auth' => [...],
    'request' => [
        'trn_id'  => $iPayTransactionId,
        'amount'  => 750.00, // частинковий повернення
        'comment' => 'Повернення по запиту клієнта',
    ],
];
Http::post('https://api.ipay.ua/api/v1/transactions/refund', $body);

Терміни активації — 2–4 робочих дні після верифікації. Ліміти на транзакції в перші місяці роботи — уточнювати у менеджера.