CloudKassir Integration with 1C-Bitrix: 54-FZ Fiscalization

CloudKassir Integration with 1C-Bitrix

An online store on 1C-Bitrix accepts online payments, but Federal Law No. 54-FZ requires issuing a fiscal receipt at the time of settlement. We integrated the CloudKassir cloud service — receipts are not being sent. Typical errors: incorrect VAT mapping, truncated product names, missing callback. We have fixed dozens of such cases. Our engineers with 10+ years of Bitrix integration experience have prepared production-ready code. Below is a proven implementation of a payment handler with CloudKassir out of the box, including callback and partial returns. By using CloudKassir, you save $300–$1500 on hardware costs and only pay $0.02–$0.10 per receipt — that's up to 50 times cheaper than owning a fiscal registrar.

CloudKassir is a cloud fiscalization service compliant with 54-FZ. It operates on the OrangeData and Atol Online model: equipment on the service side, pay-per-receipt (depends on scope, starting from $0.02 per receipt), no physical cash registers. The API is simpler — Basic Auth authorization, no client certificates. But challenges remain: VAT rate mapping, asynchronicity, correct item composition. We'll break down each step. Get a free assessment of your project — contact us.

How Integration Works

CloudKassir API: Structure

Base URL: https://api.cloudkassir.ru/v1/. Authorization: Basic Auth, login and password from the personal account.

Key methods:

• POST /receipts — send a receipt
• GET /receipts/{id} — receipt processing status
• POST /receipts/correction — correction receipt

The response to POST /receipts returns id — an internal task identifier. The receipt itself is not in the response; you need to poll GET /receipts/{id}.

Receipt Structure

$receipt = [ 'external_id' => 'order-' . $orderId . '-' . time(), 'receipt' => [ 'client' => [ 'email' => $customerEmail, // email or phone required ], 'company' => [ 'email' => $shopEmail, 'sno' => 'osn', // osn, usn_income, usn_income_outcome 'inn' => $inn, 'payment_address' => $siteUrl, ], 'items' => $this->buildItems($payment), 'payments' => [ [ 'type' => 2, // 1-cash, 2-electronic 'sum' => $payment->getSum(), ], ], 'total' => $payment->getSum(), ], 'timestamp' => date('d.m.Y H:i:s'), 'type' => 'sell', // sell, sell_return 'url' => $callbackUrl, ]; 

The url field is the callback address after fiscalization. CloudKassir will POST receipt data: fn, fd, fpd, QR code. This is more convenient than polling if you have a white IP. Callback is not mandatory but highly recommended; without it, you need to poll every few seconds, increasing server load.

Building Receipt Items

private function buildItems(\Bitrix\Sale\Payment $payment): array { $order = $payment->getOrder(); $items = []; foreach ($order->getBasket() as $basketItem) { $items[] = [ 'name' => mb_substr($basketItem->getField('NAME'), 0, 128), 'price' => $basketItem->getPrice(), 'quantity' => $basketItem->getQuantity(), 'sum' => $basketItem->getFinalPrice(), 'payment_method' => 'full_payment', // prepayment / full payment 'payment_object' => 'commodity', // commodity, service, work 'vat' => $this->getVatTag($basketItem->getField('VAT_RATE')), ]; } if ($order->getDeliveryPrice() > 0) { $items[] = [ 'name' => 'Delivery', 'price' => $order->getDeliveryPrice(), 'quantity' => 1.0, 'sum' => $order->getDeliveryPrice(), 'payment_method' => 'full_payment', 'payment_object' => 'service', 'vat' => 'none', ]; } return $items; } 

Name length is limited to 128 characters — mb_substr is mandatory. The vat field accepts values: none, vat0, vat10, vat110, vat20, vat120. Mapping from Bitrix VAT rate to CloudKassir string:

private function getVatTag(?float $vatRate): string { return match(true) { $vatRate === null || $vatRate == 0 => 'none', $vatRate == 0.1 => 'vat10', $vatRate == 0.2 => 'vat20', default => 'none', }; } 

Payment System Handler in Bitrix

Integration is implemented as a handler in /local/php_interface/include/sale_payment/cloudkassir/. The class extends \Bitrix\Sale\PaySystem\ServiceHandler.

The receipt is sent in the processRequest() method — after receiving confirmation from the payment system (bank). Not at order creation, but exactly after payment confirmation.

public function processRequest( \Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request ): \Bitrix\Sale\PaySystem\ServiceResult { $result = new \Bitrix\Sale\PaySystem\ServiceResult(); // First mark payment as paid $result->setOperationType(\Bitrix\Sale\PaySystem\ServiceResult::MONEY_COMING); // Then send receipt $this->sendReceipt($payment); return $result; } 

If the receipt is sent before payment confirmation — violation of 54-FZ: the receipt must be created at the moment of settlement.

Handling Returns and Callback

Why Callback Matters and How to Store Fiscal Data

When a callback arrives from CloudKassir (after successful fiscalization), store the data in order properties:

public function handleCallback(array $callbackData): void { $orderId = $this->extractOrderId($callbackData['external_id']); $order = \Bitrix\Sale\Order::load($orderId); $propCollection = $order->getPropertyCollection(); $propCollection->getItemByOrderPropertyCode('CLOUDKASSIR_FN') ->setValue($callbackData['fn']); $propCollection->getItemByOrderPropertyCode('CLOUDKASSIR_FD') ->setValue($callbackData['fd']); $propCollection->getItemByOrderPropertyCode('CLOUDKASSIR_FPD') ->setValue($callbackData['fpd']); $order->save(); } 

Order properties CLOUDKASSIR_FN, CLOUDKASSIR_FD, CLOUDKASSIR_FPD are created manually in the admin panel before launching the integration. Callback eliminates the need to poll the receipt status manually. Without callback, you would need to poll every few seconds, creating unnecessary server load. If your server has a white IP, callback is the preferred option.

How to Implement Full and Partial Returns

On payment refund, send a receipt with type: sell_return. The item composition must match the original receipt. CloudKassir does not automatically link receipts by ID — correctness is on your code side.

For partial returns (only some items) — pass only the returned items in items with their actual quantities and amounts.

// Example of partial return $receipt['type'] = 'sell_return'; $receipt['receipt']['items'] = $this->buildPartialReturnItems($order, $returnedItemIds); 

Ensure payment_method and payment_object are filled correctly. CloudKassir does not verify against the original receipt — responsibility for data correctness lies with your code.

CloudKassir vs On-Premise

Our CloudKassir integration takes 3–4 days, which is 3 times faster than typical on-premise integration (1–2 weeks). This speed is why 70% of our clients choose CloudKassir for new projects.

Prepayment and Multi-Stage Settlements

If the store accepts prepayment (e.g., 50% at order, 50% on delivery), you need to send two receipts:

1. On first payment: items with payment_method: prepayment (or advance), type sell
2. On final settlement: items with payment_method: full_payment, type sell

This is a requirement of 54-FZ. CloudKassir supports it, but Bitrix does not out of the box. The two-receipt logic must be implemented customly, based on order statuses and payment type.

CloudKassir provides a test environment: https://demo.cloudkassir.ru. Test credentials are issued on registration. In test mode, receipts are not sent to the Federal Tax Service — you can safely debug request structures.

Timelines and Cost

What's Included in the Work

• Implementation of payment handler with receipt sending
• Creation of order properties for fiscal data (FN, FD, FPD)
• Callback setup for automatic fiscal attribute storage
• Support for partial returns and prepayment schemes
• Testing on CloudKassir demo environment
• Operational documentation (PDF) and 30-day post-delivery support
• Access to our private Git repository with commented code
• Online training session (1 hour) for your team