Integration of 1C-Bitrix with Belagroprombank's online acquiring system

1C-Bitrix Integration with Belagroprombank Internet Acquiring

Belagroprombank is one of Belarus's key state banks, with a strong presence in the agro-industrial sector and regional markets. The bank's internet acquiring supports Visa, Mastercard, and Belkart cards. For agricultural enterprises, online stores selling agri-goods, and regional retailers whose primary bank is Belagroprombank, connecting its acquiring is a logical choice: having the payment gateway and the settlement account at the same bank simplifies reconciliation.

Belagroprombank API

The bank provides a REST API for internet acquiring. Endpoint: https://payment.bapb.by/api/v2/ (production); the test endpoint is provided on request after signing a test agreement.

Authentication: Basic Auth (merchantLogin:merchantPassword) or token via OAuth 2.0 (depending on the contract version).

Key operations:

• POST /orders — register a new order in the gateway system
• GET /orders/{orderId}/status — check transaction status
• POST /orders/{orderId}/void — cancel authorization
• POST /orders/{orderId}/refund — refund
• POST /erip/bills — create an ERIP invoice

Implementing the Handler in 1C-Bitrix

Standard approach — a custom payment system handler at /local/php_interface/include/sale_payment/bapb_acquiring/.

Order registration request:

{
  "merchantId": "BAPB_MERCHANT_ID",
  "orderNumber": "BXORDER_34567",
  "amount": 156800,
  "currency": "BYN",
  "returnUrl": "https://shop.by/order/success/34567/",
  "failUrl": "https://shop.by/order/fail/34567/",
  "notificationUrl": "https://shop.by/bitrix/tools/sale_ps_result.php",
  "description": "Online store: order #34567",
  "sessionTimeoutSecs": 1200
}

sessionTimeoutSecs is the payment session lifetime in seconds. Default is 1200 (20 minutes). If the customer does not complete the payment within this time, the session closes. This must be taken into account in 1C-Bitrix when displaying the "awaiting payment" page.

Belkart: Specifics

Belagroprombank is one of the Belkart card issuers in Belarus, making its acquiring particularly reliable for accepting Belkart cards. There are no technical differences in the request — the gateway automatically determines the card type. However, it is mandatory during testing to verify payment specifically with a Belkart card: banks sometimes apply different limits for Belkart vs Visa/Mastercard.

Notifications and Statuses

POST notifications to notificationUrl:

Notification verification — HMAC-SHA256 or via IP whitelist (Belagroprombank IP list). Confirm with the bank at connection time.

Two-Stage Payment

For made-to-order goods or stock-check scenarios, the bank supports a two-stage flow:

1. POST /orders with twoStage: true — funds are blocked only (status APPROVED)
2. POST /orders/{orderId}/deposit — actual debit after availability is confirmed

In 1C-Bitrix this is implemented as a "Confirm debit" button in the order admin area — the ProcessRequestDeposit method calls the bank's API.

Reporting and Reconciliation

Belagroprombank provides an API for retrieving transaction registers: GET /reports/transactions?dateFrom=...&dateTo=.... For accounting this is convenient — automatically download the report at end of day and reconcile with 1C-Bitrix data. Discrepancies signal unprocessed notifications.

Real Case: Delayed Refund

A Belarusian garden equipment store. A customer returned goods; the manager clicked "Issue refund" in the 1C-Bitrix admin — the API returned success. But the money appeared on the customer's card 8 business days later instead of the expected 3. Cause: the store operated under a two-stage payment contract, and for refunding a "reserved" (not yet debited) amount the void method had to be used, not refund. The refund method applied to already-debited amounts and went through a longer processing cycle. The fix was to update the condition in the handler — void for APPROVED status, refund for DEPOSITED.

Timeline