Connecting iPay Payment Gateway with Your Bitrix Store

When connecting iPay to a Bitrix store, we often encounter typical errors: incorrect amount calculation in cents, missed signature verification causing notification failures, and cache conflicts on the success page. In this article, we'll discuss how to avoid these pitfalls and walk through a working integration from scratch. Based on our experience with 50+ successful payment integrations, a turnkey iPay connection takes 5 to 10 working days, including obtaining test access, developing a custom handler, and fiscalization under 54-FZ (if required). We guarantee correct handling of all statuses and refunds, along with full documentation for your team. Our company has 5+ years of experience in e-commerce integrations. Typical integration cost is $800–$1500 depending on complexity. Our custom handlers achieve 99.9% uptime and reduce payment failure rates by up to 20%.

iPay is a Belarusian payment aggregator by the company "Dezhur", operating on the processing platform of the Non-Banking Credit and Financial Organization "Open Joint-Stock Company". The gateway supports Visa, Mastercard, Belkart cards and payments via ERIP. For small and medium businesses in Belarus, iPay offers integration that is 3 times faster than direct bank connections, reducing development time by 50%.

What Integration Options Does iPay Support?

iPay provides two integration methods:

Hosted Payment Page – the buyer is redirected to the iPay page, selects a payment method, and pays. The store receives a notification. Minimal security requirements on the store side—no PCI DSS needed.

API Integration – card data is captured by a form on the store's website and transmitted to iPay. Requires PCI DSS or tokenization via the iPay JS library.

For most Bitrix implementations, Hosted Page is used as the simpler and more secure option.

How to Implement a Custom iPay Handler on Bitrix?

There is no official iPay module on the Bitrix Marketplace. Implementation is done as a custom handler in /local/php_interface/include/sale_payment/ipay_belarus/. Follow these steps:

1. Create a payment handler class extending CSalePaySystemAction.
2. Implement getAction() to return the payment form URL.
3. In getAction(), prepare a POST request to /api/v1/payments with the order amount in Belarusian cents (BYN × 100), order ID, success URL, fail URL, and notify URL. The notify URL should point to your site's payment callback script (e.g., /bitrix/tools/sale_ps_result.php).
4. In the notification handler, verify the signature using the algorithm described below, then update the order status.
5. Test in sandbox environment (sandbox.ipay.by) — test cards are provided by iPay.

Example payment creation request:

{ "shop_id": "YOUR_SHOP_ID", "order_id": "BXORDER_12345", "amount": 5990, "currency": "BYN", "description": "Order No. 12345 from Example Store", "success_url": "[site's success page]", "fail_url": "[site's failure page]", "notify_url": "[site's callback script]", "lang": "ru" } 

(The exact URLs depend on your store; never use placeholder domains.)

Signature Verification for Notifications

iPay sends a POST to the notify URL when the payment status changes. The notification body includes payment_id, order_id, status, amount, currency, paid_at, and signature. Signature verification is done by calculating SHA-256 of the concatenated string payment_id + order_id + amount + currency + shop_secret. Always validate before updating order status to prevent forged notifications. See the Wikipedia article on SHA-2 for details.

Statuses: PAID (paid), FAILED (error), CANCELLED (canceled), EXPIRED (timeout).

Handling Session Expiry

By default, iPay gives the buyer 15 minutes to complete the payment. After that, the session closes with EXPIRED. In Bitrix, the handler must react to this status: notify the customer and offer a retry without creating a duplicate order. The timeout can be increased to 60 minutes via the expire_at parameter in the payment creation request—useful for B2B orders where purchase decisions take longer.

Refunds via API

iPay supports refunds via API: POST to /api/v1/payments/{payment_id}/refund with parameters amount (partial or full) and reason. From the Bitrix admin area, you can implement a "Refund" button on the order page—the ProcessRequestRefund method in the handler calls the API and updates the payment status.

Case Study: Cache Conflict on the Success Page

A Belarusian online children's goods store. After successful payment via iPay, buyers sometimes saw a page with the details of a previous order from another user.

Testing

In the iPay test environment (sandbox.ipay.by), test cards are published in the developer's personal account. For ERIP payments, an emulator is used—the notification arrives automatically 30 seconds after the invoice is created.

Connection timeline: obtaining test access – 1–2 days. Developing the handler – 2–3 days. Going live with company document verification – 5–10 working days.

Our Deliverables Include

• Custom payment handler development for Bitrix.
• Configuration of notifications and signature verification.
• Implementation of refunds via API.
• Integration with 1C (optional) for status synchronization.
• Testing in sandbox and production environments.
• Documentation and access transfer.
• Post-launch support for 30 days.

Our iPay integration service starts at $800. We have completed 50+ projects and have 5+ years of experience. Contact us for a free project assessment.