Setting up Internet acquiring on 1C-Bitrix

Setting Up Internet Acquiring on 1C-Bitrix

Internet acquiring is one of the first modules configured when launching an online store. In practice, "connecting an acquiring service" involves several distinct tasks: registering with the payment system, installing and configuring the handler in 1C-Bitrix, setting up callback notifications, testing, and handling fiscal law compliance where applicable. Each of these contains nuances that are not obvious during the setup phase.

Choosing a Payment System and Acquiring Service

The choice of acquiring service affects the technical implementation. Main options for the Russian market:

Installing and Configuring the Handler

The standard path for ready-made modules:

1. Module installation — via Marketplace → Solution Catalog or by uploading an archive to /bitrix/updates/
2. Creating a payment system — Store → Settings → Payment Systems → Add
3. Parameter configuration — filling in the shopId/merchantId, secretKey/password, notification URL fields

The critically important parameter during configuration is the notification URL (callback URL). For the standard 1C-Bitrix handler, this is:

https://myshop.ru/bitrix/tools/sale_ps_result.php

This URL must:

• Be accessible from the payment system's servers (not protected by basic auth)
• Work without redirects
• Return HTTP 200 on successful processing

Payment System Handler Structure

If a custom handler is required or a ready-made module is not suitable:

// /local/php_interface/include/sale_payment/my_gateway/handler.php
use Bitrix\Sale\PaySystem;

class MyGatewayHandler extends PaySystem\ServiceHandler
{
    // Initiates payment — redirects the buyer
    public function initiatePay(
        \Bitrix\Sale\Payment $payment,
        \Bitrix\Main\Request $request
    ): PaySystem\ServiceResult {
        $result = new PaySystem\ServiceResult();
        // Build the payment gateway URL and redirect
        $result->setPaymentUrl($this->buildPaymentUrl($payment));
        return $result;
    }

    // Processes an incoming notification from the gateway
    public function processRequest(
        \Bitrix\Sale\Payment $payment,
        \Bitrix\Main\Request $request
    ): PaySystem\ServiceResult {
        $result = new PaySystem\ServiceResult();

        if ($this->verifyRequest($request) && $this->isPaymentSucceeded($request)) {
            $payment->setPaid('Y');
            $result->setOperationType(PaySystem\ServiceResult::MONEY_COMING);
        }

        return $result;
    }

    // Verify the request signature
    private function verifyRequest(\Bitrix\Main\Request $request): bool
    {
        $sign = $request->get('sign');
        $expected = hash_hmac('sha256',
            $request->get('orderId') . $request->get('amount'),
            $this->getBusinessValue(null, 'SECRET_KEY')
        );
        return hash_equals($expected, $sign);
    }
}

Handler metadata (.description.php) and settings (.settings.php) follow the sale.paysystem.handler standard.

Testing

The mandatory minimum before going live:

• Successful payment with a test card → order transitions to "Paid" status
• Callback is received and processed correctly
• Repeated payment of an already paid order does not duplicate the status
• Buyer closed the browser after payment — status is still updated via callback

Timeline