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

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

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

How can you avoid typical mistakes when connecting payment systems on 1C-Bitrix?

The most common mistake during integration is forgetting about the callback. The customer paid for the order, the money was debited, but the status in b_sale_order did not update: the manager sees "Awaiting payment" and starts calling the client. The reason is an incorrect URL in the gateway settings or a handler that returns a 500 error for an atypical response structure. We offer services for connecting payment systems on 1C-Bitrix with full testing of all scenarios: successful payment, refusal, timeout, partial refund, duplicate callback.

Why are callbacks critical?

Each payment gateway sends a notification to your server. If the handler does not guarantee idempotency, a double call will lead to a double charge. We always implement a check by notification ID (external_id) and block repeated processing in \Bitrix\Sale\Order. It is also critical to set the callback URL in the aggregator's personal account – /bitrix/tools/sale_ps_result.php for the standard module. If you use a custom handler, we verify that it returns HTTP 200 even in case of parameter errors (the gateway should not repeat the request indefinitely).

use Bitrix\Sale\Order;
use Bitrix\Main\Application;

// Get notification data
$data = Application::getInstance()->getContext()->getRequest()->toArray();
// Check signature (depends on aggregator)
if (!checkSignature($data, 'SECRET_KEY')) {
    die('FAIL');
}
// Find order by external ID
$order = Order::loadByExternalId((int)$data['order_number']);
if ($order && $order->isPaid() === false) {
    $order->setField('PAYED', 'Y');
    $order->save();
}
echo 'OK';

How do we optimize payment flow for higher conversion?

How to choose a payment aggregator for 1C-Bitrix?

The choice of aggregator depends on the geography of customers, average order value, and need for installments. For Russia, the basic set is YooKassa (all main methods, fiscalization out of the box) and CloudPayments (widget on the page without redirect, Apple Pay). If you work with large corporate clients, add Sberbank (SberPay, SBP). For international sales, use Stripe or PayPal. We often use a two-tier scheme: main aggregator + backup (auto-switching on failure).

What payment gateways and methods do we use?

YooKassa

One contract – all main methods: Visa/MasterCard/MIR cards, YooMoney, SberPay, internet banking, installments. Fiscalization under 54-FZ out of the box (via the sale module). The standard handler /bitrix/modules/sale/handlers/paysystem/yandexpay/ covers basic scenarios. For holding (two-stage payment), subscriptions, or split payments, custom integration via YooKassa API v3. Callback is configured to /bitrix/tools/sale_ps_result.php, we parse notification and update \Bitrix\Sale\Order via setField('PAYED', 'Y').

CloudPayments

Focused on conversion: the payment widget directly on the checkout page, without redirect to an external domain. The customer does not leave the site – the abandonment rate during payment drops. It supports recurring payments (card tokenization via cryptogram), Apple Pay, and Google Pay. 3D Secure with intelligent routing – requested only for high fraud risk. Integration with Bitrix – via CloudPayments REST API and a custom handler in the sale module.

Tinkoff Payment

API integration via TinkoffPaymentAPI (ready-made module or manual implementation). QR code for payment via the app, "Tinkoff Credit" installment – critical for expensive goods. Partial refunds via the Cancel method – without calling the bank, everything from the Bitrix admin panel.

Sberbank (SberPay and SBP)

SberPay – payment via push notification or QR, SBP – commission 0.4–0.7% vs 1.5–2.5% for cards. This is a significant savings on volume. Holding via registerPreAuth / deposit API. Note that SberPay requires a separate agreement with the bank.

Apple Pay and Google Pay

Payment in two clicks, without entering card data. They are connected through an aggregator (YooKassa, CloudPayments, Tinkoff). Important nuances:

• Apple Pay requires domain verification: the file apple-developer-merchantid-domain-association in /.well-known/. Without it, the button will not appear.
• Button placement strictly according to Apple and Google guidelines – otherwise rejection in review.
• Fallback to the standard payment form if the device does not support contactless payment.

How do we handle installments, BNPL, and 54-FZ compliance?

If the average order value is above 30,000 RUB and conversion drops, installment removes the price barrier. We connect:

• Tinkoff Installment (3–24 months)
• Buy with Sber
• Mokka / Dolyami – BNPL: 4 payments, 0% for the buyer

Integration: widget with monthly payment calculation on the product card ("from 2,500 RUB/month"), order data transfer to the bank via API, status processing (approval, rejection, awaiting documents) in OnSaleStatusOrder handlers.

Fiscalization under 54-FZ is a mandatory requirement. The fine for a missing receipt is up to 100% of the payment amount. In accordance with Federal Law No. 54-FZ, an electronic receipt must be sent to the buyer. We connect ATOL Online, Orange Data, Module.Kassa, Evotor, Shtrikh-M. Setup in Bitrix – the "Cash Registers" section in the sale module:

• VAT rate, item and method of payment – an error in any field can lead to a fine during inspection.
• Receipts for prepayment and partial payment (two receipts: at payment and at shipment).
• Refund receipts upon cancellation via \Bitrix\Sale\Cashbox\Cashbox::addChecks().
• Monitoring: if the receipt is not sent, an alert to the manager.

When selling shoes, clothing, or perfumes, it is mandatory to transfer marking codes in the receipt. Integration with "Chestny ZNAK", scanning DataMatrix during order assembly, automatic removal from circulation upon sale via \Bitrix\Catalog\Product\Marking.

Payment support: refunds, multicurrency, security

Refunds

Full and partial refund without calling the bank – via the aggregator API (refund / cancel). The refund receipt is generated automatically, the order status is updated, the amount is recalculated, and the customer is notified. Timeframes: e-wallets and SBP – 1–3 days, bank card – up to 30 business days (depends on the issuing bank).

Multicurrency

Price types in b_catalog_price for each currency, rates via the Central Bank API (\Bitrix\Currency\CurrencyManager::updateCBRFRates()) or manual input. Conversion at the catalog level – the customer sees prices in their currency. For accepting dollars/euros, we connect Stripe, PayPal. We take into account conversion fees when calculating margin.

Security

Card data is processed on the certified gateway side (PCI DSS) – the card number never passes through your server. Anti-fraud at the aggregator level. Logging all events in b_sale_order_change for audit. Anomaly monitoring: transaction spike, atypical geography – alert.

How we work and estimated timelines

1. Analysis – what payment methods are needed, markets, transaction volume, current aggregator.
2. Solution selection – sometimes two aggregators are better than one: YooKassa as the main, CloudPayments as backup – if one fails, traffic goes to the second.
3. Integration – we test each scenario: successful payment, 3DS refusal, gateway timeout, double callback, partial refund.
4. Fiscalization – online cash register, checking the correctness of receipts on test orders.
5. Monitoring – alerts for gateway failures, conversion dashboard at the payment stage.

What is included in the work

• Full setup of selected payment systems in 1C-Bitrix: modules, handlers, callbacks, testing.
• Integration documentation (gateway operation scheme, handler description, logic).
• Training your manager to work with payment modules and refunds.
• Technical support during launch and the first 2 weeks of operation.
• Monitoring – we set up alerts for errors and conversion drops.

All work is performed by certified 1C-Bitrix developers. We guarantee the operability of each scenario. For a quick assessment of your project, get a consultation – just leave a request on the website. Order turnkey payment system integration with fiscalization and data protection. Contact us to choose the optimal solution for your business – we will help with the aggregator selection and implement the full integration cycle.