1C-Bitrix Integration with Belarusbank Internet Acquiring
Belarusbank is the largest state bank in Belarus, through whose acquiring a significant share of non-cash payments in the country are processed. Belarusbank internet acquiring includes acceptance of Visa, Mastercard, and Belkart cards, as well as ERIP invoice issuance — all through a single gateway. For stores that hold their account at Belarusbank, this is often the most straightforward solution: one bank, one contract, one gateway.
Belarusbank API Structure
Belarusbank uses a SOAP/XML-based gateway for internet acquiring (legacy version) and a REST API (new version, recommended for new integrations). The REST API operates via https://payment.belarusbank.by/api/.
Core REST API methods:
-
POST /payment/create— create a payment session -
GET /payment/status/{paymentId}— transaction status -
POST /payment/confirm— confirmation for two-stage payments -
POST /payment/refund— refund -
POST /erip/invoice/create— create an ERIP invoice
Authorization via Bearer token obtained by requesting /auth/token with client_id and client_secret.
Integration with 1C-Bitrix
Implemented as a custom handler at /local/php_interface/include/sale_payment/belarusbank_acquiring/. There is no official module on the Bitrix Marketplace.
Payment creation request:
{
"merchantId": "YOUR_MERCHANT_ID",
"orderId": "BXORDER_23456",
"amount": 23400,
"currency": "BYN",
"description": "Payment for order #23456",
"returnUrl": "https://shop.by/thank-you/?id=23456",
"failUrl": "https://shop.by/payment-fail/?id=23456",
"notifyUrl": "https://shop.by/bitrix/tools/sale_ps_result.php",
"language": "ru",
"paymentMethod": "CARD"
}
For ERIP, paymentMethod is changed to ERIP, and the response returns invoice details instead of a payment page URL.
Belkart Cards: Mandatory Support
Belarusbank internet acquiring includes processing of Belkart cards — the national payment system of Belarus. Belkart cards are widely used by payroll clients of state enterprises. When connecting Belarusbank acquiring, Belkart support is enabled automatically — no additional configuration is required, but it is important to test a payment with a Belkart test card, not only Visa/Mastercard.
3D-Secure and Declines
Belarusbank requires 3D-Secure for all card transactions. During 3DS, the customer is redirected to the card-issuing bank's confirmation page. In 1C-Bitrix this is transparent — everything happens on the payment gateway page. However, logs must be analyzed using errorCode from the payment/status response:
| Code | Description | Typical Cause |
|---|---|---|
0000 |
Success | — |
0001 |
Bank decline | Insufficient funds, card blocked |
0005 |
System decline | 3DS error or timeout |
0012 |
Invalid transaction | Card does not support online payments |
0051 |
Insufficient funds | — |
Handling Notifications
Belarusbank sends a POST notification to notifyUrl. Notification body:
{
"paymentId": "bb_pay_789012",
"orderId": "BXORDER_23456",
"status": "PAID",
"amount": 23400,
"currency": "BYN",
"timestamp": "2024-12-20T11:45:22+03:00",
"signature": "sha256_signature"
}
Signature verification — HMAC-SHA256 of paymentId + orderId + amount + currency + secret. After successful verification and PAID status — $payment->setPaid('Y').
Refunds
The API supports both full and partial refunds via POST /payment/refund:
{
"paymentId": "bb_pay_789012",
"amount": 11700,
"reason": "Partial refund by agreement"
}
In the 1C-Bitrix admin area, a refund can be implemented as a button on the order page calling ProcessRequestRefund. Belarusbank processes refunds within 1–3 business days.
Real Case: SOAP vs REST
A Belarusian online sporting goods store was running on an old SOAP integration with Belarusbank. When the bank updated its service, the SOAP gateway began returning Service Unavailable errors during peak load periods. Analysis showed: the old gateway had entered limited support mode; the new REST API is more stable. Migrating from SOAP to the REST handler took 3 business days — including refactoring the response parsing and adapting the notification processing logic.
Timeline
Signing the Belarusbank internet acquiring contract takes 5 to 15 business days. Handler development and testing — 2–4 business days. Belarusbank provides a test environment with test cards immediately after signing the test agreement.