Integrate Kapital Bank payments with 1C-Bitrix

Integrate Kapital Bank payments with 1C-Bitrix If your 1C-Bitrix online store does not accept Kapital Bank cards — the largest bank in Azerbaijan with over 40% market share in online payments — you are losing up to 30% of buyers. Integrating this bank is not just adding a payment method; it incre
11+Years of work900+Completed projects100+In house employees19+Partners
Services we offer
Showing 1 of 1All 1626 services
Integrate Kapital Bank payments with 1C-Bitrix
Medium
~1-2 weeks

Our competencies:

Frequently Asked Questions

Integrate Kapital Bank payments with 1C-Bitrix

If your 1C-Bitrix online store does not accept Kapital Bank cards — the largest bank in Azerbaijan with over 40% market share in online payments — you are losing up to 30% of buyers. Integrating this bank is not just adding a payment method; it increases trust: a familiar logo on the checkout page boosts conversion by 15–20%. We have been developing payment modules for Bitrix since 2013 and have completed over 50 payment system integration projects. In 3–5 days we connect Kapital Bank HPP so your customers from Azerbaijan can pay with Visa and Mastercard. All we need from you is the Merchant ID and secret key; we handle the rest. Get a consultation within a day. Basic HPP integration starts from $350 (standard store), with refund support from $600.

Kapital Bank connection methods

The bank offers two options: HPP (Hosted Payment Page) and Direct API. HPP is the standard method for 95% of merchants: the customer is redirected to the bank's page, enters card details, and the site receives a callback with the result. This method does not require PCI DSS certification — security is entirely handled by the bank. Direct API involves direct transmission of card data via the API, which requires PCI DSS and is rarely used (mobile apps, non-standard scenarios). For a typical store, HPP is 5 times faster to implement and 30% cheaper than Direct API, with no extra bureaucratic constraints. HPP integration costs 30–40% less, and conversion is higher due to trust in the bank's page.

How HPP integration with Kapital Bank works

  1. The customer selects card payment on the site.
  2. The system generates an XML request with the amount (in qəpik: 1 AZN = 100 qəpik) and sends it to the bank's REST endpoint via cURL with TLS 1.2 encryption.
  3. The bank responds with OrderId and SessionId — these are used to build the HPP redirect URL.
  4. The customer enters card details on the bank's page, protected by 3DSecure authentication.
  5. Upon success, the bank sends a callback to ApproveURL — our handler verifies the response via checksum (HMAC-SHA256) and updates the order status after a redundant GetOrderStatus call to prevent duplicate orders.

We implement a custom handler based on \Bitrix\Sale\PaySystem\ServiceHandler with methods initiatePay(), processRequest(), and refund(). Details are in the request structure below.

Request structure to the bank API

When initiating a payment, a POST request is sent to the endpoint:

  • Test: https://tstpg.kapitalbank.az/api/order/
  • Production: https://pg.kapitalbank.az/api/order/

Body — XML with UTF-8 encoding (without BOM):

<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>

Response contains OrderId and SessionId, based on which the redirect URL is formed. After payment, the bank calls ApproveURL with these same parameters. In processRequest() we make an additional GetOrderStatus request — the callback may contain a signature, but we verify it using the secret key via HMAC-SHA256 to ensure authenticity.

Refund handling

Kapital Bank supports two types of refunds:

  • Reverse — full refund on the day of the transaction.
  • Refund — partial or late refund.

The handler implements the refund() method, which is called from the Bitrix admin panel when an order status is changed to "Refund". In the b_sale_payment table, the PS_INVOICE_ID field stores the OrderId from the bank — it is used to initiate the refund.

Handling missing callbacks

Sometimes the payment goes through but the order status is not updated. Typical causes:

  • The callback URL is not accessible externally (check firewall and web server settings, ensure HTTP 200 response).
  • The bank's IP is blocked.
  • The XML request is sent in the wrong encoding.

We always add logging of incoming requests to the callback endpoint to quickly identify the problem. We also implement idempotency keys to avoid duplicate order processing. In our projects, after testing, the turnaround time is 3–5 days, and during that time we guarantee stable handler operation.

Testing and typical issues

Testing table
Stage What we check
Order creation Correct amount (in qəpik — 1 AZN = 100 qəpik), Currency = 944
Redirect to HPP URL contains both parameters: ORDERID and SESSIONID
Callback processing Order status changes, duplicate calls ignored via idempotency key
Test cards Visa 4169741330151124, CVC 119, any future date
Production Change endpoint and credentials, check SSL certificate

A common error is XML encoding mismatch (the bank expects UTF-8 without BOM). When using curl in PHP, we always set Content-Type: text/xml; charset=utf-8.

Step-by-step setup of the Kapital Bank handler

  1. Obtain Merchant ID and secret key from the bank.
  2. In the Bitrix admin panel, go to Store → Payment systems and create a new system.
  3. Select the KapitalBank handler and enter Merchant ID, password, and mode (test/production).
  4. Set default currency — AZN.
  5. Configure order statuses for successful payment and error.
  6. Ensure the callback URL is accessible externally and returns HTTP 200.
  7. Perform a test payment using a test card.

The sale.order.ajax component on the site requires no changes — redirection to HPP is handled by the standard Bitrix mechanism via BX_PAYMENT_REDIRECT.

How to avoid integration errors?

  • Always check the amount in qəpik (multiply AZN by 100).
  • Ensure XML is sent with UTF-8 encoding without BOM.
  • Add logging of incoming callback requests for debugging.
  • Do not trust the callback directly — make an additional GetOrderStatus request.
  • Set up monitoring of order statuses: if a callback notification fails, the order remains in "awaiting payment" status.

Timelines and scope of work

Project scale Scope Timeline Estimated cost
Standard store HPP module + testing + documentation 3–5 days $350–$600
With partial refunds + Refund method, admin UI 5–7 days $600–$900
Multiple stores (multisite) + configuration per site +1–2 days +$150 per site

Get a consultation for your project — we will assess complexity and provide details. Contact us to order turnkey integration. Start accepting payments via Kapital Bank in as little as 3 days.

Source: Wikipedia, Kapital Bank

1C Bitrix presentation1C Bitrix24 presentation1C Enterprise presentation