Integration of 1C-Bitrix with the Alfa-Bank acquiring payment system

Integration of 1C-Bitrix with Alfa-Bank Payment System

Alfa-Bank is one of the most common payment gateways for Russian online stores. It provides a REST API for accepting card payments with support for 3-D Secure, hold, and refunds.

How the Integration Works

Standard payment scenario:

1. Customer selects card payment and clicks "Pay"
2. Bitrix creates an order, calls the order registration method in Alfa-Bank API
3. API returns orderId and formUrl (payment form URL)
4. Customer is redirected to Alfa-Bank payment form
5. After payment — redirect to store returnUrl
6. Alfa-Bank sends callback to failUrl/returnUrl or via separate webhook
7. Bitrix checks status via API, confirms payment

Connection: What You Need to Get From the Bank

• Login and password for test and production gateway (or token instead of login/password)
• Gateway URL — test (https://alfa.rbsuat.com/payment/rest/) and production (https://pay.alfabank.ru/payment/rest/)
• Access to personal account for transaction monitoring

Implementing a Payment System Handler

Alfa-Bank is connected as a payment system of the sale module. Handler files structure in /local/php_interface/include/sale_payment/alfa_bank/:

handler.php        — handler class
.description.php   — metadata
.settings.php      — settings: login, password, gateway URL, mode (test/live)
template/          — button template

Handler class inherits from \Bitrix\Sale\PaySystem\ServiceHandler. Key methods:

initiatePay — order registration and form URL retrieval:

public function initiatePay(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request = null)
{
    $order = $payment->getOrder();
    $sum   = $payment->getSum();

    $params = [
        'userName'   => $this->getBusinessValue($payment, 'ALFA_LOGIN'),
        'password'   => $this->getBusinessValue($payment, 'ALFA_PASSWORD'),
        'orderNumber'=> $order->getId(),
        'amount'     => (int)($sum * 100),   // in kopecks
        'currency'   => 643,                 // RUB
        'returnUrl'  => $this->getReturnUrl($payment),
        'failUrl'    => $this->getReturnUrl($payment) . '?fail=1',
        'description'=> 'Payment for order #' . $order->getId(),
    ];

    $response = $this->apiRequest('register.do', $params);

    if (!empty($response['errorCode']) && $response['errorCode'] !== '0') {
        return \Bitrix\Sale\PaySystem\ServiceResult::createError($response['errorMessage']);
    }

    // Save Alfa-Bank orderId for later verification
    $this->saveAlfaOrderId($payment, $response['orderId']);

    return \Bitrix\Sale\PaySystem\ServiceResult::createRedirect($response['formUrl']);
}

processRequest — process customer return and status verification:

public function processRequest(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request)
{
    $alfaOrderId = $this->getAlfaOrderId($payment);
    if (!$alfaOrderId) {
        return \Bitrix\Sale\PaySystem\ServiceResult::createError('Alfa orderId not found');
    }

    $status = $this->apiRequest('getOrderStatus.do', [
        'userName' => $this->getBusinessValue($payment, 'ALFA_LOGIN'),
        'password' => $this->getBusinessValue($payment, 'ALFA_PASSWORD'),
        'orderId'  => $alfaOrderId,
    ]);

    // orderStatus: 2 = paid
    if (isset($status['orderStatus']) && $status['orderStatus'] == 2) {
        $payment->setPaid('Y');
        return \Bitrix\Sale\PaySystem\ServiceResult::create();
    }

    return \Bitrix\Sale\PaySystem\ServiceResult::createError('Payment not confirmed');
}

Two-Stage Payments (Hold)

Alfa-Bank supports a two-stage scheme: first hold (registerPreAuth.do), then confirmation (deposit.do) or reversal (reverse.do). For stores with payment after verifying product availability, this is the correct scheme.

// Hold
$response = $this->apiRequest('registerPreAuth.do', $params);

// Confirmation (when shipping goods)
$this->apiRequest('deposit.do', [
    'userName' => $login,
    'password' => $password,
    'orderId'  => $alfaOrderId,
    'amount'   => (int)($sum * 100),
]);

Refunds

Alfa-Bank API supports full and partial refunds via the refund.do method:

$this->apiRequest('refund.do', [
    'userName' => $login,
    'password' => $password,
    'orderId'  => $alfaOrderId,
    'amount'   => (int)($refundAmount * 100),  // partial refund
]);

Refund is initiated from Bitrix code when canceling an order. Add a handler for the OnSaleOrderCanceled event:

AddEventHandler('sale', 'OnSaleOrderCanceled', function(\Bitrix\Main\Event $event) {
    $order = $event->getParameter('ENTITY');
    // Find payment with the needed payment system, call refund.do
});

Fiscalization (FZ-54)

For online stores required to issue receipts, Alfa-Bank supports passing receipt data in the order registration request via the taxSystem parameter and the orderBundle object with order items. Items are taken from Bitrix basket ($order->getBasket()), VAT rates from catalog settings.

Testing

In Alfa-Bank test environment, use card 4111111111111111, expiry 12/26, any CVV. Test should include full cycle: registration → form → payment → return to site → status check → payment update in Bitrix.

Development Timeline