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

1C-Bitrix Integration with the ERIP Payment System (Belarus)

ERIP (Unified Settlement and Information Space) is Belarus's national payment infrastructure, through which the vast majority of utility, government, and commercial payments are processed. For a Belarusian online store, the absence of ERIP from the list of payment methods represents a significant conversion loss: a large share of payments in the country goes through this system rather than through card acquiring.

How ERIP Works for Online Stores

Unlike card acquiring, ERIP is not "pay right now on the website." The flow is different:

1. The store registers an invoice in ERIP via its bank agent's API
2. The customer receives a unique invoice number (or QR code)
3. The customer pays independently through any bank, ATM, terminal, or app connected to ERIP
4. The system sends a payment notification to the store

There is no direct ERIP API — interaction goes through the bank where the company's settlement account is held. Each bank provides its own API or gateway for issuing ERIP invoices. Belarusbank, Priorbank, Alfa-Bank, MTBank — each has its own protocol, though the underlying logic is similar.

Technical Integration in Bitrix

Since no single ERIP API exists, the integration is built as a custom payment system handler in the sale module, adapted to a specific bank's API.

Typical handler structure in /local/php_interface/include/sale_payment/erip/:

handler.php         — invoice registration and status check logic
.description.php    — metadata, name, ERIP icon
.settings.php       — bankApiUrl, merchantId, apiKey, serviceCode
template/           — display of payment details to the customer

Key handler methods:

• initiatePay — calls the bank API to register an invoice, receives billId and eripQrCode, stores them in payment fields
• processRequest — processes the bank's webhook upon payment receipt
• checkPayment — active status polling (used as a fallback if the webhook was not received)

Invoice Registration Parameters

A typical request to the bank API for registering an ERIP invoice:

{
  "merchantId": "YOUR_MERCHANT_ID",
  "serviceCode": "ERIP_SERVICE_CODE",
  "invoiceNumber": "ORD-12345",
  "amount": 125.50,
  "currency": "BYN",
  "description": "Payment for order #12345",
  "expireAt": "2024-12-31T23:59:59",
  "callbackUrl": "https://yourshop.by/bitrix/tools/sale_ps_result.php",
  "returnUrl": "https://yourshop.by/personal/order/detail/12345/"
}

serviceCode is your service code in the ERIP service tree. It is assigned when onboarding with the bank. This is how customers find your store in the ERIP menu ("Online Stores → Category → Your Store").

Displaying Payment Details to the Customer

After the invoice is issued, the customer needs to see:

• The ERIP invoice number (or QR code) for manual payment
• Instructions: "Internet banking → ERIP → Search by number" or the path through the service tree
• Invoice expiry time
• QR code for quick payment via a mobile banking app

The template/ of the payment system component is responsible for this screen. The standard Bitrix "Thank you for your order" page does not work here — you need a payment-pending page with dynamic status updates via AJAX or WebSocket.

Notification Handling and Payment Confirmation

The bank sends a POST notification to callbackUrl upon payment receipt. The handler must:

1. Verify the request signature (each bank uses its own method — HMAC, RSA, or IP whitelist)
2. Find the payment by invoiceNumber or billId
3. Verify that the amount matches (the customer may have paid a partial amount)
4. Call $payment->setPaid('Y') only for a full payment
5. Update the order status according to the store's business logic

Partial payment is an ERIP-specific feature. The system allows an invoice to be paid in multiple transactions. If this is undesirable, set the partialPaymentAllowed: false flag when registering the invoice.

Real-World Case: Amount Mismatch

A Belarusian building materials store. A customer paid the ERIP invoice but the order was never confirmed — managers started investigating two hours later. Cause: the customer paid 124.50 BYN instead of 125.50 BYN (entered the wrong amount manually). The system recorded the payment, but the handler did not confirm it due to the amount mismatch. Fix: add an automatic manager notification for "nearly full" payments (deviation up to 1% or 1 BYN) and provide a manual confirmation interface in the admin panel.

Timelines and Stages

Service registration in the ERIP tree is the longest stage and does not depend on the developer. Start it in parallel with development.