1C-Bitrix Integration with PayKeeper Payment System

Integrating the PayKeeper payment gateway with 1C-Bitrix is a task that every store owner faces when wanting full control over payments. Without proper notification handling and fiscalization, your store risks losing money and facing fines. We have been solving this problem for over 50 projects—from e-commerce stores to B2B portals, saving clients up to 150,000 rubles per year.

Recently we deployed PayKeeper for a store processing 10,000 orders per month. The requirements included full 54-FZ fiscalization and refund handling. Result: payment time dropped to 15 seconds, and commission was 20% lower than with YooKassa, saving up to 100,000 rubles per month on a turnover of 1 million rubles. Integration cost starts from 30,000 rubles and varies by complexity. PayKeeper offers 99.9% uptime guarantee.

How PayKeeper Works

PayKeeper is a PHP application that runs as a payment server on your domain or in the cloud. The store creates an invoice via API, obtains the payment form URL, and the buyer enters card details. Payment notifications are sent to result_url. As per PayKeeper documentation, all requests are protected by an MD5 signature.

PayKeeper Integration Step-by-Step Process

The process consists of the following steps: 1) Install module, 2) Create invoice via API, 3) Handle notifications, 4) Test all scenarios.

Step 1: Install and Configure the Module

Install the PayKeeper module from Bitrix Marketplace or our custom module. In the payment system settings, enter your PayKeeper server URL, username, and secret password. Ensure HTTPS is enabled.

Step 2: Create Invoice via API

Use the code below to create an invoice. Replace placeholders with your actual credentials.

$apiUrl      = $this->getBusinessValue($payment, 'PAYKEEPER_URL'); // https://your.paykeeper.ru
$clientId    = $this->getBusinessValue($payment, 'PAYKEEPER_USER');
$clientSecret = $this->getBusinessValue($payment, 'PAYKEEPER_PASSWORD');
$orderId     = $payment->getOrder()->getId();
$sum         = $payment->getSum();

// Get token
$tokenResponse = $this->httpPost($apiUrl . '/info/settings/token/', [], [
    'Authorization: Basic ' . base64_encode("{$clientId}:{$clientSecret}"),
]);
$token = $tokenResponse['token'];

// Create invoice
$invoiceParams = [
    'pay_amount'    => number_format($sum, 2, '.', ''),
    'clientid'      => $payment->getOrder()->getUserId(),
    'orderid'       => $orderId,
    'client_email'  => $email,
    'client_phone'  => $phone,
    'service_name'  => 'Payment for order #' . $orderId,
];
$invoiceParams['token'] = md5(implode('', $invoiceParams) . $token);

$invoice = $this->httpPost($apiUrl . '/change/invoice/preview/', $invoiceParams);
// $invoice['invoice_id'] — invoice ID
// Payment form: $apiUrl . '/?id=' . $invoice['invoice_id']

Step 3: Handle Payment Notifications

PayKeeper sends POST to result_url upon payment. Verify the signature and confirm the order.

$clientSecret = $this->getBusinessValue($payment, 'PAYKEEPER_PASSWORD');

$id        = $_POST['id'];
$sum       = $_POST['sum'];
$orderId   = $_POST['orderid'];
$key       = $_POST['key'];

// Check signature
$expected = md5($id . $sum . $orderId . $clientSecret);
if (strtolower($key) !== strtolower($expected)) {
    http_response_code(400);
    echo 'bad signature';
    exit;
}

// Additional check via API
$paymentInfo = $this->httpGet($apiUrl . '/info/payments/byid/', ['id' => $id], $token);
if ($paymentInfo['status'] === 'paid') {
    // Confirm payment in Bitrix
    $order = \Bitrix\Sale\Order::loadByAccountNumber($orderId);
    // ... setPaid('Y'), save()
}

echo 'OK';

Step 4: Test All Scenarios

Test successful payment, failed payment, refund, and partial refund. Ensure fiscalization works.

Why Choose PayKeeper?

PayKeeper is 20% cheaper than YooKassa when turnover exceeds 1 million rubles per month, saving you up to 100,000 rubles monthly. Customer data stays on your server—you are not dependent on an external gateway. Unlike Robokassa, you have full control: your own domain, your own certificates. PayKeeper supports invoices, refunds, and fiscalization. It can be self-hosted on your own server or VPS, offering maximum security and data privacy. The API URL is unique per store, so in Bitrix payment system settings you need a field for the PayKeeper server URL rather than hardcoding it.

Refunds and Fiscalization

PayKeeper supports refunds via API:

$refundParams = [
    'id'     => $paykeeperPaymentId,
    'amount' => number_format($refundAmount, 2, '.', ''),
];
$refundParams['token'] = md5(implode('', $refundParams) . $token);

$result = $this->httpPost($apiUrl . '/change/payment/return/', $refundParams);

To comply with Federal Law 54-FZ, PayKeeper has built-in integration with online cash registers (OFD). Receipt data is transmitted when creating an invoice via basket parameters. The item composition is taken from $order->getBasket(). We configure the transmission of all requisites and guarantee correct fiscalization of refunds.

Error Handling and Security

PayKeeper may be temporarily unavailable or return a timeout error. Therefore, a queue mechanism should be added to the integration code:

// If payment not confirmed, retry in 5 minutes
if ($attempt < 3) {
    \Bitrix\Sale\PaymentCollection::addToQueue([
        'order_id' => $orderId,
        'attempt'  => $attempt + 1,
        'next_try' => (new \DateTime())->modify('+5 minutes')
    ]);
}

Log all requests and responses from PayKeeper for debugging. Save POST requests and responses with timestamps in a table like b_sale_payment_log.

Security requirements of 54-FZ and personal data protection:

• Do not transmit full card numbers in logs—mask the last 4 digits
• Use HTTPS for all requests (disable certificate check only in development)
• Store PAYKEEPER_PASSWORD only in .env or a protected config table, never in HTML

Typical Integration Mistakes

• Not verifying the notification signature. Without checking key, an attacker can forge notifications—always validate the md5 with the secret.
• Hardcoding the server URL. PayKeeper may be installed on any domain—use settings in the admin panel, not constants.
• Ignoring fiscalization of partial refunds. In a partial refund, transmit only the returned items—critical for OFD.
• Missing notification queue. If result_url hangs, the payment remains unprocessed. Add a background job that queries the status every hour.
• Confusing payment statuses. PayKeeper returns paid, failed, cancelled—handle each status correctly in Bitrix.

What Our Work Includes

Deliverables

• Module: Ready-to-use Bitrix module with PayKeeper integration (supports Cloud and On-Premise)
• Documentation: Configuration guide, admin manual, and support documentation for your team
• Access: Admin panel access for payment system settings and log inspection
• Training: 2-hour online training for your staff on module usage and troubleshooting (reduced emphasis)
• Support: 1 month post-integration support (email, phone, and remote assistance)

Approximate Timelines

The cost is calculated individually. We work with any Bitrix version and guarantee compatibility with the latest updates. Contact us for a project evaluation and get a free consultation on PayKeeper integration.

How can you avoid typical mistakes when connecting payment systems on 1C-Bitrix?

The most common mistake during integration is forgetting about the callback. The customer paid for the order, the money was debited, but the status in b_sale_order did not update: the manager sees "Awaiting payment" and starts calling the client. The reason is an incorrect URL in the gateway settings or a handler that returns a 500 error for an atypical response structure. We offer services for connecting payment systems on 1C-Bitrix with full testing of all scenarios: successful payment, refusal, timeout, partial refund, duplicate callback.

Why are callbacks critical?

Each payment gateway sends a notification to your server. If the handler does not guarantee idempotency, a double call will lead to a double charge. We always implement a check by notification ID (external_id) and block repeated processing in \Bitrix\Sale\Order. It is also critical to set the callback URL in the aggregator's personal account – /bitrix/tools/sale_ps_result.php for the standard module. If you use a custom handler, we verify that it returns HTTP 200 even in case of parameter errors (the gateway should not repeat the request indefinitely).

use Bitrix\Sale\Order;
use Bitrix\Main\Application;

// Get notification data
$data = Application::getInstance()->getContext()->getRequest()->toArray();
// Check signature (depends on aggregator)
if (!checkSignature($data, 'SECRET_KEY')) {
    die('FAIL');
}
// Find order by external ID
$order = Order::loadByExternalId((int)$data['order_number']);
if ($order && $order->isPaid() === false) {
    $order->setField('PAYED', 'Y');
    $order->save();
}
echo 'OK';

How do we optimize payment flow for higher conversion?

How to choose a payment aggregator for 1C-Bitrix?

The choice of aggregator depends on the geography of customers, average order value, and need for installments. For Russia, the basic set is YooKassa (all main methods, fiscalization out of the box) and CloudPayments (widget on the page without redirect, Apple Pay). If you work with large corporate clients, add Sberbank (SberPay, SBP). For international sales, use Stripe or PayPal. We often use a two-tier scheme: main aggregator + backup (auto-switching on failure).

What payment gateways and methods do we use?

YooKassa

One contract – all main methods: Visa/MasterCard/MIR cards, YooMoney, SberPay, internet banking, installments. Fiscalization under 54-FZ out of the box (via the sale module). The standard handler /bitrix/modules/sale/handlers/paysystem/yandexpay/ covers basic scenarios. For holding (two-stage payment), subscriptions, or split payments, custom integration via YooKassa API v3. Callback is configured to /bitrix/tools/sale_ps_result.php, we parse notification and update \Bitrix\Sale\Order via setField('PAYED', 'Y').

CloudPayments

Focused on conversion: the payment widget directly on the checkout page, without redirect to an external domain. The customer does not leave the site – the abandonment rate during payment drops. It supports recurring payments (card tokenization via cryptogram), Apple Pay, and Google Pay. 3D Secure with intelligent routing – requested only for high fraud risk. Integration with Bitrix – via CloudPayments REST API and a custom handler in the sale module.

Tinkoff Payment

API integration via TinkoffPaymentAPI (ready-made module or manual implementation). QR code for payment via the app, "Tinkoff Credit" installment – critical for expensive goods. Partial refunds via the Cancel method – without calling the bank, everything from the Bitrix admin panel.

Sberbank (SberPay and SBP)

SberPay – payment via push notification or QR, SBP – commission 0.4–0.7% vs 1.5–2.5% for cards. This is a significant savings on volume. Holding via registerPreAuth / deposit API. Note that SberPay requires a separate agreement with the bank.

Apple Pay and Google Pay

Payment in two clicks, without entering card data. They are connected through an aggregator (YooKassa, CloudPayments, Tinkoff). Important nuances:

• Apple Pay requires domain verification: the file apple-developer-merchantid-domain-association in /.well-known/. Without it, the button will not appear.
• Button placement strictly according to Apple and Google guidelines – otherwise rejection in review.
• Fallback to the standard payment form if the device does not support contactless payment.

How do we handle installments, BNPL, and 54-FZ compliance?

If the average order value is above 30,000 RUB and conversion drops, installment removes the price barrier. We connect:

• Tinkoff Installment (3–24 months)
• Buy with Sber
• Mokka / Dolyami – BNPL: 4 payments, 0% for the buyer

Integration: widget with monthly payment calculation on the product card ("from 2,500 RUB/month"), order data transfer to the bank via API, status processing (approval, rejection, awaiting documents) in OnSaleStatusOrder handlers.

Fiscalization under 54-FZ is a mandatory requirement. The fine for a missing receipt is up to 100% of the payment amount. In accordance with Federal Law No. 54-FZ, an electronic receipt must be sent to the buyer. We connect ATOL Online, Orange Data, Module.Kassa, Evotor, Shtrikh-M. Setup in Bitrix – the "Cash Registers" section in the sale module:

• VAT rate, item and method of payment – an error in any field can lead to a fine during inspection.
• Receipts for prepayment and partial payment (two receipts: at payment and at shipment).
• Refund receipts upon cancellation via \Bitrix\Sale\Cashbox\Cashbox::addChecks().
• Monitoring: if the receipt is not sent, an alert to the manager.

When selling shoes, clothing, or perfumes, it is mandatory to transfer marking codes in the receipt. Integration with "Chestny ZNAK", scanning DataMatrix during order assembly, automatic removal from circulation upon sale via \Bitrix\Catalog\Product\Marking.

Payment support: refunds, multicurrency, security

Refunds

Full and partial refund without calling the bank – via the aggregator API (refund / cancel). The refund receipt is generated automatically, the order status is updated, the amount is recalculated, and the customer is notified. Timeframes: e-wallets and SBP – 1–3 days, bank card – up to 30 business days (depends on the issuing bank).

Multicurrency

Price types in b_catalog_price for each currency, rates via the Central Bank API (\Bitrix\Currency\CurrencyManager::updateCBRFRates()) or manual input. Conversion at the catalog level – the customer sees prices in their currency. For accepting dollars/euros, we connect Stripe, PayPal. We take into account conversion fees when calculating margin.

Security

Card data is processed on the certified gateway side (PCI DSS) – the card number never passes through your server. Anti-fraud at the aggregator level. Logging all events in b_sale_order_change for audit. Anomaly monitoring: transaction spike, atypical geography – alert.

How we work and estimated timelines

1. Analysis – what payment methods are needed, markets, transaction volume, current aggregator.
2. Solution selection – sometimes two aggregators are better than one: YooKassa as the main, CloudPayments as backup – if one fails, traffic goes to the second.
3. Integration – we test each scenario: successful payment, 3DS refusal, gateway timeout, double callback, partial refund.
4. Fiscalization – online cash register, checking the correctness of receipts on test orders.
5. Monitoring – alerts for gateway failures, conversion dashboard at the payment stage.

What is included in the work

• Full setup of selected payment systems in 1C-Bitrix: modules, handlers, callbacks, testing.
• Integration documentation (gateway operation scheme, handler description, logic).
• Training your manager to work with payment modules and refunds.
• Technical support during launch and the first 2 weeks of operation.
• Monitoring – we set up alerts for errors and conversion drops.

All work is performed by certified 1C-Bitrix developers. We guarantee the operability of each scenario. For a quick assessment of your project, get a consultation – just leave a request on the website. Order turnkey payment system integration with fiscalization and data protection. Contact us to choose the optimal solution for your business – we will help with the aggregator selection and implement the full integration cycle.