YooKassa Payment Integration in 1C-Bitrix

Imagine: a customer places an order, proceeds to payment — but after a successful transaction, the webhook never arrives, the order status doesn't update, and the money hangs in limbo. YooKassa (formerly Yandex.Kassa) is one of the most popular payment aggregators in Russia, but the standard module from the Marketplace doesn't cover all scenarios. We've faced situations where notifications didn't come through, refunds failed with errors, and fiscalization produced invalid receipts. According to official YooKassa documentation, REST API version 3 allows flexible transaction management but requires careful setup. Over five years, we've completed more than 50 integrations — from simple stores to B2B platforms with tens of thousands of monthly transactions. Below, we break down the technical details and show how to avoid common pitfalls.

How YooKassa Works Technically

YooKassa provides a REST API (api.yookassa.ru/v3/). The classic payment flow:

1. The store sends POST /payments with amount, currency, and confirmation.type=redirect — YooKassa returns payment.id and confirmation.confirmation_url.
2. The customer is redirected to the YooKassa payment page.
3. After payment, YooKassa sends a webhook notification to the return_url and a POST to the configured notification URL.
4. The store calls GET /payments/{id} for final status verification.

Authentication: HTTP Basic with shopId:secretKey or OAuth token.

Supported payment methods: bank cards, SBP, YooMoney, SberPay, Tinkoff, QIWI (with limitations), cash via terminals. The method is passed in payment_method_type or chosen by the customer on the YooKassa form.

Why Choose Custom Integration

The official YooKassa module for Bitrix is available for free and works for standard stores. However, it has limitations: rigid binding to standard components, difficulty customizing order statuses, and lack of flexible fiscalization. A custom handler solves these issues and allows integrating YooKassa with any non-standard entities. Our experience shows that custom integration handles non-standard tasks 2-3 times faster than modifying the ready module. We are certified specialists with over 5 years of experience, guaranteeing correct operation across all scenarios. Contact us to evaluate your project — get a consultation on integration and exact timelines for your case.

How to Configure Webhooks for YooKassa

YooKassa sends a POST to the configured URL whenever the payment status changes. In Bitrix, the default handler URL is /bitrix/tools/sale_ps_result.php. Critical points:

• Verify the source IP address. YooKassa publishes its IP ranges: 185.71.76.0/27, 185.71.77.0/27, 77.75.153.0/25, 77.75.156.11, 77.75.156.35. Without filtering, you risk fake notifications.
• Verify the status via API. Don't trust webhook data directly — make a GET /payments/{id} for double-checking.
• Only handle terminal statuses. pending and waiting_for_capture do not require order changes.

// Sample handling $body = file_get_contents('php://input'); $notification = json_decode($body, true); $payment = $client->getPaymentInfo($notification['object']['id']); switch ($payment->getStatus()) { case 'succeeded': $bitrixPayment->setPaid('Y'); $bitrixPayment->save(); break; case 'canceled': // Log the cancellation reason break; } 

Key Request Parameters

// Minimal payment creation request via SDK use YooKassa\Client; $client = new Client(); $client->setAuth($shopId, $secretKey); $payment = $client->createPayment([ 'amount' => [ 'value' => number_format($order->getPrice(), 2, '.', ''), 'currency' => 'RUB', ], 'confirmation' => [ 'type' => 'redirect', 'return_url' => 'https://shop.ru/personal/order/detail/' . $order->getId() . '/', ], 'capture' => true, // false for two-stage payments 'description' => 'Order #' . $order->getAccountNumber(), 'metadata' => ['bitrix_order_id' => $order->getId()], 'receipt' => $receiptData, // mandatory if online cash register is connected ], uniqid('', true)); // idempotency key 

capture: true — single-stage payment, funds are charged immediately. capture: false — two-stage: YooKassa holds the amount, and the store calls POST /payments/{id}/capture upon shipment.

The idempotency key (third parameter) is mandatory. Without it, a repeated request due to a network error will create a duplicate payment.

Fiscalization (54-FZ) and Why It's Mandatory

The requirements of 54-FZ (on the use of cash register equipment) apply to all online payments. YooKassa acts as a fiscal registrar, sending data to the OFD. If your YooKassa contract includes receipt transmission, the receipt object in the request becomes mandatory. Without it, the transaction will be rejected — this is one of the most common problems. The receipt structure must exactly match 54-FZ requirements. We use a proven schema with breakdown by VAT rates and item attributes. The total amount of all items in the receipt must exactly match the payment amount — YooKassa checks this on their side. Refunds also require a receipt that mirrors the original items. The official YooKassa documentation provides receipt structure examples, but we adapt them to your specifics.

Payment Statuses and Refunds

YooKassa supports partial and full refunds via POST /refunds. If a cash register is connected, a refund without a receipt is rejected. The refund receipt mirrors the original receipt items with type refund. We've implemented over 50 successful integrations with refunds, guaranteeing correct accounting.

Testing

YooKassa provides a test environment with the same endpoints. In test mode (shopId=test_...), payments proceed with test cards:

• 5555555555554477 — successful payment
• 5555555555554444 — decline

Be sure to test: successful payment, cancellation, delayed webhook (customer closes the browser before redirect), and partial refund. This helps avoid issues on the live site.

What's Included

• Audit of the current Bitrix configuration and trade catalog
• Development or refinement of the payment handler (with 54-FZ compliance)
• Webhook configuration and notification handling
• Testing all scenarios in the test environment
• Integration documentation and operator instructions
• 30-day warranty support after commissioning

Timelines and How to Start

Contact us to evaluate your project. Get a consultation on integration and exact timelines for your case. For more details, refer to the official YooKassa API documentation. About 54-FZ requirements, read on Wikipedia.