Интеграция платёжной системы 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 рабочих дня после верификации. Лимиты на транзакции в первые месяцы работы — уточнять у менеджера.