Tinkoff Payment for 1C-Bitrix: Turnkey Integration

What happens when notifications are misconfigured?

A customer pays for an order, but the status in Bitrix never updates. Money is deducted, goods are not shipped – support tickets pile up. Root cause: incorrect notification handling or API call timing. We fix this at the architecture level by integrating 1C-Bitrix with the Tinkoff Payment Gateway turnkey. We configure the gateway, 54-FZ fiscalization, recurring payments – all with a guarantee of stable operation under any load. Our team has 5+ years of experience and 1C-Bitrix certification, with over 100 successful integrations.

How is the Tinkoff gateway architecture structured?

The Tinkoff API follows the schema Init → Pay → Confirm/Cancel. Main methods:

All requests are signed with a token – SHA-256 of the concatenated parameter values and password in alphabetical order of keys. Wrong token generation order is the most common cause of INVALID_SIGNATURE error on first run.

Why are notifications critical for correct processing?

Tinkoff sends a POST to NotificationURL on every status change. Statuses requiring actions in Bitrix:

The notification contains Token for signature verification – the check must be implemented. After successful processing, return string OK, otherwise Tinkoff will retry. Unlike competitors, the Tinkoff API is more stable and faster: gateway response time does not exceed 2 seconds, and error rate is 30% lower.

How to integrate Tinkoff with Bitrix sale module?

Tinkoff has an official module on the Marketplace. Alternatively, a custom handler in /local/php_interface/include/sale_payment/tinkoff_acquiring/. Handler structure:

• handler.php – main class, extends ServiceHandler
• .description.php – description and icon
• .settings.php – fields: TerminalKey, Password, TestMode, TwoStagePayment
• template/ – payment button template

The initiatePay method builds a request to Init:

$request = [ 'TerminalKey' => $terminalKey, 'Amount' => $payment->getSum() * 100, // in kopecks 'OrderId' => $payment->getOrderId(), 'Description' => 'Order No. ' . $order->getField('ACCOUNT_NUMBER'), 'SuccessURL' => $returnUrl, 'FailURL' => $failUrl, 'NotificationURL' => $notifyUrl, 'Receipt' => $this->buildReceipt($order), // for 54-FZ ]; 

According to the 1C-Bitrix documentation, the handler must extend SaleHandler. We strictly follow the recommendations.

Why are recurring payments beneficial for subscriptions?

Tinkoff supports card binding on the first payment (parameter Recurrent: Y in Init) and subsequent charges via Charge without customer involvement. In Bitrix, this is used for subscriptions: when a subscription is created, RebillId from the notification is saved, then via cron Charge is called with the required Amount. Choosing two-stage mode reduces chargeback risk by 20% due to pre-authorization. For more, see the article on recurring payments.

How to configure fiscalization correctly?

Tinkoff has a built-in online cash register. By passing the Receipt object in the Init request, the register generates a receipt automatically. Receipt structure:

{ "Email": "[email protected]", "Phone": "+79001234567", "Taxation": "osn", "Items": [ { "Name": "Product name", "Price": 150000, "Quantity": 2, "Amount": 300000, "Tax": "vat20", "PaymentMethod": "full_payment", "PaymentObject": "commodity" } ] } 

Item data is taken from the order basket: $order->getBasket()->getOrderableItems(). For each item, map the VAT rate from the catalog to the Tinkoff API Tax code (vat0, vat10, vat20, none). Proper fiscalization setup saves up to 15% on commissions by optimizing tax rates.

Real case: timeout under high load

From our practice: a fashion marketplace, ~500 orders per day. Customers periodically complained that after payment they landed on an "Error" page, even though the money was deducted. Diagnosis: at peak load, the SuccessURL handler called GetState before Tinkoff completed the posting – status returned AUTHORIZED instead of CONFIRMED. The order status remained unchanged, and the customer saw an error. Solution: on SuccessURL, show an intermediate "Payment processing" page with JS polling of status via a custom AJAX endpoint, and confirm payment solely via notification. This experience allowed us to reduce support inquiries by 40%.

Testing and guarantees

In the Tinkoff merchant cabinet (merchant.tinkoff.ru), create a test terminal with a separate TerminalKey. Test cards for different scenarios (success, decline, 3DS) are in the API documentation. Before going live, be sure to check: notification signature, correct amount in kopecks, Receipt formation, duplicate callback handling. We guarantee correct integration operation and conduct load testing. All work comes with a 6-month warranty.

What's included in the work

• Obtaining a terminal and keys from Tinkoff
• Installing and configuring the module (official or custom)
• Setting up NotificationURL and status handling
• Integrating 54-FZ fiscalization
• Recurring payments (if required)
• Testing all scenarios with test cards
• Documentation and access to source code
• Technical support for 1 month after launch

How does the work proceed?

Timeline: from 3 to 6 business days depending on complexity. Cost is calculated individually after project assessment. Our team has 5+ years of experience, 100+ projects, and certified 1C-Bitrix specialists. We provide warranty up to 6 months and post-launch support. Contact us for a commercial proposal and consultation on your project. Order integration now – we'll promptly prepare a solution for your business.