Интеграция 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);
    }
}

Сертификаты хранятся вне директории web-сервера, путь к ним — в опциях модуля.

Создание платёжной сессии

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} мес.`;

Сроки