We integrate 1C-Bitrix with Belarusbank internet acquiring — the largest state bank in Belarus, through which a significant share of non-cash payments in the country pass. The bank supports acceptance of Visa, Mastercard, and Belcard cards, as well as invoicing via ERIP through a single gateway. For stores with an account at Belarusbank, this is the optimal solution: one bank, one contract, one integration. Our experience includes over 50 projects with Belarusian banks, and we know all the pitfalls. There is no direct integration on the Marketplace — each project requires custom development for specific needs: product type, payment volume, ERIP requirement. Savings on transaction costs can reach 30% compared to using multiple payment gateways.
How the integration with Bitrix works?
Implemented as a custom handler in /local/php_interface/include/sale_payment/belarusbank_acquiring/. There is no official module on the Bitrix Marketplace — we build each project from scratch for specific requirements. We test in the Belarusbank test environment, including error scenarios and partial refunds.
Belarusbank API structure
Belarusbank uses a SOAP/XML-based gateway (older version) and a REST API (recommended for new integrations) for internet acquiring. REST API is more stable — according to our measurements, 30% fewer timeouts under load. Endpoint: https://payment.belarusbank.by/api/.
Main REST API methods:
-
POST /payment/create— create a payment session -
GET /payment/status/{paymentId}— transaction status -
POST /payment/confirm— confirm for two-stage payment -
POST /payment/refund— refund -
POST /erip/invoice/create— create an ERIP invoice
Authorization via Bearer token obtained from /auth/token with client_id and client_secret. Payment creation request:
{ "merchantId": "YOUR_MERCHANT_ID", "orderId": "BXORDER_23456", "amount": 23400, "currency": "BYN", "description": "Payment for order No. 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 changes to ERIP, and the response returns invoice details instead of a payment page URL.
Why REST API over SOAP?
Belarusbank supports two protocols: SOAP/XML (older version) and REST API (recommended). REST API is five times more stable under load: less than 1% timeouts vs. 5% for SOAP.
| Parameter | REST API | SOAP/XML |
|---|---|---|
| Stability under load | High (<1% timeouts) | Medium (up to 5% timeouts) |
| Response time (p95) | 200–400 ms | 500–1000 ms |
| Bank support priority | Priority | Deprecated |
| Integration complexity | Low (JSON) | Medium (XML with XSD) |
Real case: A Belarusian online sports goods store was running on an old SOAP integration. After the bank updated its gateway, SOAP started returning Service Unavailable errors during peak hours (up to 50% failures). Migration to REST API took 3 business days — stability restored, failures dropped to 1%. A case where protocol update paid off within the first month. Over 100,000 transactions have passed through our integration.
Peculiarities of payments: Belcard, 3D-Secure, and error handling
Belcard and 3D-Secure
Belarusbank acquiring includes processing of Belcard cards — the national payment system of Belarus. They are widely used by salary clients of state enterprises. When connecting, Belcard support is enabled automatically, but we always test payment with a test Belcard card — not just Visa/Mastercard.
Belarusbank requires 3D-Secure for all card transactions. The buyer is redirected to the issuer bank's confirmation page — transparent in Bitrix. Logs should be analyzed by errorCode from the payment/status response.
Typical errors and their resolution
Details on error codes
| 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 payment |
0051 |
Insufficient funds | — |
For code 0005, we recommend checking 3DS timeouts — if the buyer did not confirm in time, payment can be retried. Code 0012 often means the card is issued for cash withdrawal only — suggest another payment method. All errors are handled via the standard Bitrix mechanism: $payment->setField('PAY_VOUCHER_NUM', ...) and $payment->setField('STATUS_ID', 'N').
How to handle errors and refunds?
Notification handling
Belarusbank sends a POST notification to notifyUrl. Notification body:
{ "paymentId": "bb_pay_789012", "orderId": "BXORDER_23456", "status": "PAID", "amount": 23400, "currency": "BYN", "timestamp": "2024-01-01T12:00:00+03:00", "signature": "sha256_signature" } Signature verification — HMAC-SHA256 of paymentId + orderId + amount + currency + secret. After successful verification and status PAID — $payment->setPaid('Y').
Refunds
The API supports both full and partial refund via POST /payment/refund:
{ "paymentId": "bb_pay_789012", "amount": 11700, "reason": "Partial refund per agreement" } In the Bitrix admin panel, refund is implemented as a button on the order page calling ProcessRequestRefund. Belarusbank processes refunds within 1–3 business days.
Additional on ERIP: If the store integrates with ERIP, ensure the API response returns the correct eripCode and payment deadline. Belarusbank allows invoices with various validity periods (from 24 hours to 30 days). We recommend setting a validity of 3–5 days to balance conversion and non-payment risk.
Step-by-step handler setup
- Obtain test data from Belarusbank (merchantId, client_secret, notifyUrl).
- Create a custom handler in
/local/php_interface/include/sale_payment/belarusbank_acquiring/. - Implement methods:
createPayment,getStatus,processNotify,refundPayment. - Configure
notifyUrlin the bank's admin panel. - Run test payments in the test environment, including error scenarios.
Scope of work and timeline
Deliverables include:
- custom sale_payment handler with REST API support;
- notification setup (notifyUrl, notification handling);
- testing in Belarusbank's test environment;
- ERIP integration (if required);
- operational manual and support contacts;
- integration warranty: 6 months free revisions for defects.
Timeline: signing a contract with Belarusbank — from 5 to 15 business days. Development and testing — 2–4 days. Belarusbank provides a test environment immediately after signing the test agreement. Read more about the payment system on Wikipedia.
Contact us to discuss your project. Request a consultation — we will select the optimal protocol and prepare a technical specification for the bank. Investment in integration pays off within the first month due to lower fees and higher conversion.