Integration of 1C-Bitrix with the Bepaid payment system (Belarus)

Integration of 1C-Bitrix with bePaid payment system (Belarus)

bePaid is a Belarusian payment gateway, one of the main ones for accepting card payments in Belarusian online stores. Supports Visa, MasterCard, MIR, BELKART cards. Provides REST API with redirect to payment form or embedded widget.

Features of Belarusian acquiring

Belarusian online stores must work with a bank acquirer holding a license from the National Bank of the Republic of Belarus. bePaid provides such acquiring through partner banks (Belgosprombank, Priorbank and others). For connection, you need a legal entity in Belarus.

Main API URL: https://checkout.bepaid.by/ctp/api/

Integration scheme: Checkout Page

Standard method — redirect to bePaid hosted page:

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

$requestData = [
    'checkout' => [
        'test'          => $isTest,
        'transaction_type' => 'payment',  // or 'authorization' for hold
        'order' => [
            'amount'   => (int)($sum * 100),   // in kopecks (BYN: *100)
            'currency' => 'BYN',
            'description' => 'Order #' . $orderId,
            'tracking_id' => $orderId,
        ],
        'settings' => [
            'success_url'      => $successUrl,
            'decline_url'      => $failUrl,
            'fail_url'         => $failUrl,
            'notification_url' => $notificationUrl,
            'language'         => 'en',
        ],
        '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 to redirect customer
// $response['checkout']['token'] — payment token for status check

Receiving notifications

bePaid sends POST with JSON body to notification_url:

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

// Signature check via SHA1
$received = $data['transaction']['uid'] ?? '';
$hash     = $data['transaction']['verification_code'] ?? '';
$expected = sha1($secretKey . $received);

// Alternative check: via API status request by uid
$trackingId = $data['transaction']['tracking_id'];  // our orderId
$txStatus   = $data['transaction']['status'];         // 'successful', 'failed', etc.

if ($txStatus === 'successful') {
    $order = \Bitrix\Sale\Order::loadByAccountNumber($trackingId);
    // confirm payment
}

http_response_code(200);

Transaction statuses: successful — success, failed — failure, pending — processing, expired — time expired.

Refunds

$refundData = [
    'request' => [
        'parent_uid' => $originalTransactionUid,
        'amount'     => (int)($refundAmount * 100),
        'reason'     => 'Order cancellation',
    ],
];

$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));
// ...

Differences from Russian gateways

• Amounts are transmitted in Belarusian rubles (BYN), in kopecks: 10.50 BYN = 1050
• tracking_id — arbitrary string identifier of the order (unlike InvId in Robokassa)
• Support for BELKART cards — specifics of Belarusian market
• Notifications come in JSON via POST, not form-encoded

Testing

bePaid provides test environment: https://checkout.bepaid.by with flag test: true. Test card: 4200000000000000, expiry 01/30, CVV 123. Amount < 100 BYN — successful payment, >= 100 — decline.

Development timeline