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

Інтеграція 1С-Bitrix з платіжною системою Bepaid (Беларусь)

bePaid — білоруський платіжний шлюз, один з основних для прийому карткових платежів у білоруських інтернет-магазинах. Підтримує карти Visa, MasterCard, МІР, БЕЛКАРТ. Надає REST API з редиректом на платіжну форму або вбудованим віджетом.

Особливості білоруського еквайрингу

Білоруські інтернет-магазини повинні працювати з банком-еквайєром, що має ліцензію Нацбанку РБ. bePaid надає такий еквайринг через партнерські банки (Белгазпромбанк, Приорбанк та інші). Для підключення потрібне юрлицо в РБ.

Основний URL API: https://checkout.bepaid.by/ctp/api/

Схема інтеграції: Checkout Page

Стандартний спосіб — редирект на hosted-сторінку bePaid:

$credentials = base64_encode($shopId . ':' . $secretKey);

$requestData = [
    'checkout' => [
        'test'          => $isTest,
        'transaction_type' => 'payment',  // або 'authorization' для холду
        'order' => [
            'amount'   => (int)($sum * 100),   // у копійках (BYN: *100)
            'currency' => 'BYN',
            'description' => 'Замовлення №' . $orderId,
            'tracking_id' => $orderId,
        ],
        'settings' => [
            'success_url'      => $successUrl,
            'decline_url'      => $failUrl,
            'fail_url'         => $failUrl,
            'notification_url' => $notificationUrl,
            'language'         => 'uk',
        ],
        'customer' => [
            'email' => $email,
            'phone' => $phone,
        ],
    ],
];

$ch = curl_init('https://checkout.bepaid.by/ctp/api/checkouts');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Basic ' . $credentials,
    'Accept: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// $response['checkout']['redirect_url'] — URL для редиректа покупця
// $response['checkout']['token'] — токен платежу для перевірки статусу

Отримання сповіщень

bePaid відправляє POST з JSON-тілом на notification_url:

$rawBody  = file_get_contents('php://input');
$data     = json_decode($rawBody, true);

// Перевірка підпису через SHA1
$received = $data['transaction']['uid'] ?? '';
$hash     = $data['transaction']['verification_code'] ?? '';
$expected = sha1($secretKey . $received);

// Альтернативна перевірка: через API запит статусу по uid
$trackingId = $data['transaction']['tracking_id'];  // наш orderId
$txStatus   = $data['transaction']['status'];         // 'successful', 'failed', тощо

if ($txStatus === 'successful') {
    $order = \Bitrix\Sale\Order::loadByAccountNumber($trackingId);
    // підтвердити оплату
}

http_response_code(200);

Статуси транзакцій: successful — успішно, failed — неудачно, pending — в обробці, expired — вийшло час.

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

$refundData = [
    'request' => [
        'parent_uid' => $originalTransactionUid,
        'amount'     => (int)($refundAmount * 100),
        'reason'     => 'Скасування замовлення',
    ],
];

$ch = curl_init('https://gateway.bepaid.by/transactions/refunds');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Basic ' . $credentials,
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($refundData));
// ...

Відмінності від російських шлюзів

• Суми передаються в білоруських рублях (BYN), у копійках: 10.50 BYN = 1050
• tracking_id — довільна рядок-ідентифікатор замовлення (на відміну від InvId у Robokassa)
• Підтримуються карти БЕЛКАРТ — специфіка білоруського ринку
• Сповіщення приходять у JSON через POST, не form-encoded

Тестування

bePaid надає тестове середовище: https://checkout.bepaid.by з прапором test: true. Тестова карта: 4200000000000000, строк 01/30, CVV 123. Сума < 100 BYN — успішна оплата, >= 100 — відмова.

Терміни розробки