Інтеграція 1С-Бітрікс з розстрочкою Карта покупок (Білорусь)

Інтеграція 1С-Бітрікс з розстрочкою Карта покупок (Білорусь)

«Карта покупок» — програма розстрочки від Пріорбанку (Білорусь). Клієнт оплачує покупку частинами без відсотків, магазин отримує повну суму. Схема роботи схожа з іншими картами розстрочки, але API Пріорбанку має свою специфіку: автентифікація через SSL-сертифікат і окрема документація для eCommerce-партнерів.

Особливості API Пріорбанку

Пріорбанк використовує двостороннє TLS-з'єднання для підключення партнерів. Це означає: крім перевірки сертифіката сервера банку, банк перевіряє сертифікат клієнта (вашого сервера). При отриманні статусу партнера надається:

• клієнтський SSL-сертифікат (.crt)
• приватний ключ (.key)
• CA-сертифікат банку (для перевірки сервера)

Налаштування cURL для запитів з клієнтським сертифікатом:

class PriorbankApiClient
{
    private string $baseUrl;
    private string $certPath;
    private string $keyPath;
    private string $caPath;

    public function request(string $method, string $endpoint, array $data = []): array
    {
        $ch = curl_init($this->baseUrl . $endpoint);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_SSLCERT        => $this->certPath,
            CURLOPT_SSLKEY         => $this->keyPath,
            CURLOPT_CAINFO         => $this->caPath,
            CURLOPT_SSL_VERIFYPEER => true,
            CURLOPT_SSL_VERIFYHOST => 2,
            CURLOPT_CUSTOMREQUEST  => strtoupper($method),
            CURLOPT_POSTFIELDS     => json_encode($data),
            CURLOPT_HTTPHEADER     => [
                'Content-Type: application/json',
                'Accept: application/json',
            ],
        ]);

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode >= 400) {
            throw new \RuntimeException("Пріорбанк API: HTTP {$httpCode}: {$response}");
        }

        return json_decode($response, true);
    }
}

Сертифікати зберігаються поза директорією веб-сервера, шлях до них — в опціях модуля.

Створення платіжної сесії

public function initiatePay(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request = null)
{
    $order = $payment->getOrder();
    $basket = $order->getBasket();
    $items = [];

    foreach ($basket as $item) {
        $items[] = [
            'name'     => $item->getField('NAME'),
            'quantity' => $item->getQuantity(),
            'price'    => $item->getPrice(),
            'sku'      => $item->getProductId(),
        ];
    }

    $payload = [
        'partner_id'       => $this->getBusinessValue($payment, 'PARTNER_ID'),
        'order_ref'        => (string)$order->getId(),
        'amount'           => $payment->getSum(),
        'currency'         => 'BYN',
        'term'             => (int)$this->getBusinessValue($payment, 'INSTALLMENT_TERM'), // місяці
        'items'            => $items,
        'customer'         => [
            'first_name' => $order->getPropertyValueByCode('NAME'),
            'last_name'  => $order->getPropertyValueByCode('LAST_NAME'),
            'phone'      => $order->getPropertyValueByCode('PHONE'),
            'email'      => $order->getPropertyValueByCode('EMAIL'),
        ],
        'success_url'      => $this->getSuccessUrl($payment),
        'fail_url'         => $this->getFailUrl($payment),
        'callback_url'     => $this->getNotificationUrl($payment),
    ];

    $response = $this->apiClient->request('POST', '/installment/create', $payload);

    if (empty($response['payment_url'])) {
        throw new \RuntimeException('Не отримано payment_url від Пріорбанку');
    }

    $this->storeSessionId($payment, $response['session_id']);

    $result = new \Bitrix\Sale\PaySystem\ServiceResult();
    $result->setPaymentUrl($response['payment_url']);
    return $result;
}

Статусна модель

Колбек від банку верифікується порівнянням підпису: банк підписує тіло запиту приватним ключем, ми перевіряємо публічним ключем банку (входить до пакету документації API).

Повернення коштів

При оформленні повернення в Бітрікс (подія OnSalePaymentEntitySaved при PAID = N для раніше оплаченого платежу) надсилаємо запит на повернення до Пріорбанку:

public function refund(\Bitrix\Sale\Payment $payment, $refundableSum)
{
    $sessionId = $this->getStoredSessionId($payment);
    $response  = $this->apiClient->request('POST', '/installment/refund', [
        'session_id' => $sessionId,
        'amount'     => $refundableSum,
        'reason'     => 'customer_request',
    ]);
    return !empty($response['refund_id']);
}

Відображення розстрочки на сайті

На сторінці товару та в кошику додаємо віджет розстрочки: при сумі замовлення N рублів — «Оплатіть частинами від X руб./міс.». Розрахунок на фронті:

const months = 12; // з налаштувань
const monthlyPayment = Math.ceil(totalPrice / months);
document.getElementById('installment-badge').textContent =
    `Розстрочка від ${monthlyPayment} руб./міс. × ${months} міс.`;

Терміни