1C-Bitrix Integration with iPay Payment System (Belarus)
iPay is a Belarusian payment aggregator by the company "Dejur", operating on the processing infrastructure of the non-banking credit-financial organization. The gateway supports Visa, Mastercard, and Belkart cards, as well as ERIP payments. For small and medium-sized businesses in Belarus, iPay often serves as an alternative to direct bank connections — with simplified documentation and a fast onboarding process.
How iPay Works
iPay offers two integration options:
Hosted Payment Page — the customer is redirected to the iPay page, selects a payment method, and pays. The store receives a notification. Minimal security requirements on the store side — PCI DSS is not required.
API integration — card data is accepted by a form on the store's website and passed to iPay. Requires PCI DSS compliance or tokenization via the iPay JavaScript library.
For most 1C-Bitrix implementations, the Hosted Page option is used as the simpler and more secure approach.
Endpoint: https://api.ipay.by/ (production), https://sandbox.ipay.by/ (test).
Technical Integration with 1C-Bitrix
There is no official iPay module on the Bitrix Marketplace. It is implemented as a custom handler at /local/php_interface/include/sale_payment/ipay_belarus/.
Payment initiation — POST request to /api/v1/payments:
{
"shop_id": "YOUR_SHOP_ID",
"order_id": "BXORDER_12345",
"amount": 5990,
"currency": "BYN",
"description": "Order #12345 at Example store",
"success_url": "https://yourshop.by/thank-you/?order=12345",
"fail_url": "https://yourshop.by/payment-error/?order=12345",
"notify_url": "https://yourshop.by/bitrix/tools/sale_ps_result.php",
"lang": "ru"
}
The amount is passed in Belarusian kopecks (BYN × 100). iPay returns a payment_id and payment_url — the customer is redirected to the latter.
Handling Notifications
iPay sends a POST request to notify_url when the payment status changes. Notification body:
{
"payment_id": "ipay_txn_98765",
"order_id": "BXORDER_12345",
"status": "PAID",
"amount": 5990,
"currency": "BYN",
"paid_at": "2024-06-15T14:32:11Z",
"signature": "sha256_hash_here"
}
Signature verification — SHA-256 of the string payment_id + order_id + amount + currency + shop_secret. Without signature verification, anyone can send a fake payment notification.
Statuses: PAID (paid), FAILED (error), CANCELLED (cancelled), EXPIRED (session expired).
Payment Session Lifetime
By default, iPay gives the customer 15 minutes to complete the payment. After expiry, the session closes with the EXPIRED status. In 1C-Bitrix this means the handler must handle timeouts: upon receiving EXPIRED — notify the customer and offer a new attempt without creating a duplicate order.
The timeout can be extended to 60 minutes using the expire_at parameter in the payment creation request — useful for B2B orders where the purchase decision takes longer.
Refunds via API
iPay supports refunds via API: POST to /api/v1/payments/{payment_id}/refund with amount (partial or full refund) and reason parameters. In the 1C-Bitrix admin area, this can be implemented as a "Refund" button on the order page — the handler's ProcessRequestRefund method calls the API and updates the payment status.
Real Case: Caching Page Conflict
A Belarusian online store for children's goods. After a successful iPay payment, customers occasionally saw a page displaying the details of another user's old order. Cause: the "thank you" page was cached by nginx, and upon redirect from success_url a cached response was returned. Fix: add the Cache-Control: no-store, no-cache header for order page URLs and ensure the ?order= parameter is read dynamically from the 1C-Bitrix session, not from the URL.
Testing
In the iPay test environment (sandbox.ipay.by), test cards are published in the developer account. For ERIP payments in test mode, an emulator is used — the notification arrives automatically 30 seconds after the invoice is created.
Connection timeline: obtaining test access — 1–2 days. Handler development — 2–3 days. Live connection with company document verification — 5–10 business days.