Integration of 1C-Bitrix with the Kapital Bank payment system (Azerbaijan)

1C-Bitrix Integration with Kapital Bank Payment System (Azerbaijan)

Kapital Bank is one of the largest banks in Azerbaijan, providing a payment gateway for internet acquiring. Integration with 1C-Bitrix allows you to accept payments via Visa, Mastercard and local instruments (Kapital Bank cards) directly on your site without redirecting the customer to third-party pages unnecessarily.

How the Kapital Bank Payment Gateway Works

The bank provides two connection options:

• Hosted Payment Page (HPP). The customer is redirected to the bank's page where they enter card data. The site receives a callback with the transaction result. Minimal PCI DSS requirements on the merchant side.
• Direct API (e-Commerce). Card data is transmitted directly via the bank's API. Requires PCI DSS SA or SAQ D certification. Used rarely — mainly for mobile apps and specific flows.

For most 1C-Bitrix projects, HPP is used: it is simpler to maintain and does not impose additional security requirements.

Payment Module in 1C-Bitrix

The payment system in Bitrix is connected via the sale.payment component. For Kapital Bank, a custom payment system handler is created — a PHP class inherited from \Bitrix\Sale\PaySystem\ServiceHandler. Main methods implemented:

• initiatePay() — forms a request to the bank's API, gets orderId and sessionId, builds the HPP redirect URL.
• processRequest() — handles incoming callback (HTTP POST or GET from the bank), verifies the signature, changes the order status.
• isPaymentExpired() — checks if the payment session has expired (usually 15–20 minutes for Kapital Bank).

Connection parameters are stored in the b_sale_pay_system_action table (handler settings): MERCHANT_ID, SECRET_KEY, ENVIRONMENT (test/prod).

API Request Structure

When initiating payment, a request is formed to the endpoint https://tstpg.kapitalbank.az/api/order/ (test) or https://pg.kapitalbank.az/api/order/ (production). Request body — XML:

<TKKPG>
  <Request>
    <Operation>CreateOrder</Operation>
    <Language>RU</Language>
    <Order>
      <OrderType>Purchase</OrderType>
      <Merchant>MERCHANT_ID</Merchant>
      <Amount>15000</Amount>
      <Currency>944</Currency><!-- AZN = 944 per ISO 4217 -->
      <Description>Order №12345</Description>
      <ApproveURL>https://site.az/payment/success/</ApproveURL>
      <CancelURL>https://site.az/payment/cancel/</CancelURL>
      <DeclineURL>https://site.az/payment/fail/</DeclineURL>
    </Order>
  </Request>
</TKKPG>

In response, the bank returns OrderId and SessionId. The customer is redirected to a URL like https://pg.kapitalbank.az/...?ORDERID=...&SESSIONID=....

After payment, the bank calls ApproveURL with parameters OrderId and SessionId. In processRequest(), status is verified via a separate GetOrderStatus request — direct parameters in the callback cannot be trusted as they may not contain a signature in some configurations.

Handling Refunds

Kapital Bank supports refunds via the Reverse operation (full refund on the day of transaction) and Refund (partial or late). The refund() method is implemented in the handler — it is called from the Bitrix admin panel when the order status is changed to "Refund".

The b_sale_payment table stores the PS_INVOICE_ID field — this is the OrderId from the bank, which is used to initiate the refund.

Testing and Typical Issues

Common error — XML encoding mismatch (bank expects UTF-8 without BOM). When working via curl in PHP, ensure the Content-Type: text/xml; charset=utf-8 header is set explicitly.

What is Configured in the Admin Panel

In the section Store → Payment Systems, a new system is created with the KapitalBank handler. Administrator fills in:

• Merchant ID and password (issued by bank)
• Operating mode (test / production)
• Default currency (AZN)
• Order statuses on successful payment and error

The sale.order.ajax component on the site does not require changes — HPP redirection is handled via Bitrix's standard mechanism through BX_PAYMENT_REDIRECT.

Timeline and Scope of Work