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

1C-Bitrix Integration with EasyPay Payment System (Belarus)

EasyPay is a Belarusian payment service operating through a network of terminals and internet acquiring. EasyPay's distinguishing feature is its extensive network of physical terminals throughout Belarus: a customer can place an order online and pay with cash at the nearest EasyPay terminal — this is relevant for an audience that does not use bank cards online. For a 1C-Bitrix store, this is a separate payment system in the sale module with a characteristic "deferred payment" logic.

EasyPay Architecture for Online Stores

EasyPay provides two operating modes for e-commerce:

Online card payment — standard acquiring. The customer enters card details on the EasyPay payment page and the money is debited immediately. A notification is sent to the store's webhook.

Terminal payment — the store creates an invoice, the customer receives a unique payment code, and pays at an EasyPay terminal. The notification arrives with a delay ranging from a few minutes to several hours, depending on the terminal network load.

API endpoint: https://checkout.easypay.by/api/ (production), https://sandbox.easypay.by/api/ (test).

Implementing the Handler in 1C-Bitrix

Placement: /local/php_interface/include/sale_payment/easypay_belarus/

Payment initiation — POST to /api/v1/invoice:

{
  "serviceId": "YOUR_SERVICE_ID",
  "accountNo": "BXORDER_45678",
  "amount": {
    "value": 7850,
    "currency": "BYN"
  },
  "info": "Order #45678",
  "returnUrl": "https://shop.by/personal/order/detail/45678/",
  "notifyUrl": "https://shop.by/bitrix/tools/sale_ps_result.php",
  "expiredAt": "2024-12-20T18:00:00+03:00"
}

The amount is in BYN kopecks. serviceId is assigned during the EasyPay onboarding.

The response contains an object with invoiceId and either paymentUrl (for online card payment) or paymentCode (code for terminal). Depending on the selected mode, the handler either redirects to paymentUrl or displays the paymentCode and instructions to the customer.

Displaying the Terminal Code

The screen after checkout for terminal payment must include:

• The unique payment code in large font
• Instructions: "EasyPay Terminal → Pay for services → Payment code → enter {code}"
• A map of nearby terminals (EasyPay provides a terminal geolocation API)
• Code expiry date and payment deadline

The payment system template in 1C-Bitrix (template/) is responsible for this screen. If the template is not customized, the customer will see a generic "Awaiting payment" screen with no instructions — a common reason for support calls.

Processing Notifications

EasyPay sends a POST to notifyUrl on successful payment:

{
  "invoiceId": "ep_inv_112233",
  "accountNo": "BXORDER_45678",
  "status": "PAID",
  "amount": 7850,
  "currency": "BYN",
  "paidAt": "2024-12-19T15:22:41+03:00",
  "paymentMethod": "TERMINAL",
  "sign": "hmac_sha256_value"
}

paymentMethod can be CARD, TERMINAL, or ERIP. The processing logic is the same regardless of method, but the order status comment can vary (e.g., "Paid via terminal" for terminal payments).

Verification of sign — HMAC-SHA256 of the string invoiceId + accountNo + amount + currency + secret.

Edge Case: Expired Invoices

Terminal payments are frequently overdue — the customer forgets to pay. EasyPay sends a status: EXPIRED notification when expiredAt is reached. 1C-Bitrix must handle this status: automatically cancel unpaid orders or leave them for a manager to handle manually.

For larger stores, a convenient approach is a cron script that checks all orders in "Awaiting payment" status older than N hours once per hour and calls the EasyPay API (GET /api/v1/invoice/{invoiceId}) to refresh the status.

Real Case: Notification Delay

An electronics store during peak days — public holidays. Complaints: orders were not confirmed immediately after terminal payment, customers were anxious. Diagnosis: the EasyPay terminal network was sending notifications with up to a 40-minute delay during high load. Fix: add JavaScript polling of the status every 30 seconds via a custom AJAX endpoint that calls the EasyPay API GET /api/v1/invoice/{invoiceId}. When PAID status is received — refresh the page without waiting for the webhook.

Timeline