Интеграция 1С-Битрикс с платёжной системой Payme (Узбекистан)

Интеграция 1С-Битрикс с платёжной системой Payme (Узбекистан)

Мы не раз сталкивались с ситуацией: интернет-магазин на Битрикс теряет до 30–40% заказов только из‑за того, что не принимает Payme — главный платёжный инструмент Узбекистана с более чем 10 млн активных пользователей. Официального модуля для Битрикс нет, и здесь нужен кастомный JSON‑RPC обработчик. Без него конверсия в регионе остаётся низкой, а клиенты уходят к конкурентам. Мы, команда с 7-летним опытом разработки на 1С-Битрикс и более 50 интеграций платёжных систем, разберём, как правильно построить интеграцию с гарантией идемпотентности и корректным учётом валюты.

Как строится Subscribe API Payme

Payme не использует редиректы — вместо этого сервер Payme вызывает ваш сервер по протоколу JSON‑RPC. Магазин реализует шесть обязательных методов, каждый из которых должен отвечать за 1–2 секунды. Нарушение тайминга — и платеж зависает.

Собственный JSON‑RPC сервер (например, local/api/payme.php) обрабатывает все эти методы, проверяет авторизацию через Basic Auth и возвращает строго определённые структуры.

Почему важна идемпотентность и как её реализовать

Если Payme дважды отправит CreateTransaction, один и тот же платёж может быть проведён дважды. Мы решаем это отдельной таблицей b_payme_transactions, где первичный ключ — payme_id. Повторный запрос с тем же payme_id возвращает существующую транзакцию, а не создаёт новую. Такой подход предотвращает двойные списания и отвечает требованиям Payme API (см. документацию JSON‑RPC).

CREATE TABLE b_payme_transactions (
    payme_id     VARCHAR(64) PRIMARY KEY,
    order_id     INT          NOT NULL,
    amount       BIGINT       NOT NULL,
    state        TINYINT      DEFAULT 1,
    create_time  BIGINT,
    perform_time BIGINT       DEFAULT 0,
    cancel_time  BIGINT       DEFAULT 0,
    reason       TINYINT      DEFAULT NULL
);

Состояния: 1 — создана, 2 — успешно выполнена, -1/-2 — отменена на разных этапах.

Типичные ошибки и их решения

Реализация сервера в Битрикс (кейс)

Точка входа — отдельный PHP‑файл, не зависящий от публичной части. В нём мы обрабатываем все шесть методов. Ниже — ключевой фрагмент для CheckPerformTransaction:

<?php
define('NO_KEEP_STATISTIC', true);
define('NOT_CHECK_PERMISSIONS', true);
require_once $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

header('Content-Type: application/json');

// Basic Auth — пароль должен совпадать с ключом из кабинета Payme
$auth = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
preg_match('/Basic (.+)/', $auth, $m);
[, $password] = explode(':', base64_decode($m[1] ?? ''), 2);
if (!hash_equals(PAYME_CASHIER_KEY, $password)) {
    echo json_encode(['error' => ['code' => -32504, 'message' => 'Auth failed']]);
    exit;
}

$body   = json_decode(file_get_contents('php://input'), true);
$method = $body['method'] ?? '';
$params = $body['params'] ?? [];
$id     = $body['id'] ?? null;

if ($method === 'CheckPerformTransaction') {
    $orderId = (int)($params['account']['order_id'] ?? 0);
    $amount  = (int)($params['amount'] ?? 0); // в тийинах

    $order = Bitrix\Sale\Order::load($orderId);
    if (!$order) {
        echo json_encode(['error' => ['code' => -31050, 'message' => ['ru' => 'Заказ не найден']], 'id' => $id]);
        exit;
    }

    // Сравниваем сумму (цены в магазине в UZS, умноженные на 100)
    $expected = (int)round($order->getPrice() * 100);
    if ($expected !== $amount) {
        echo json_encode(['error' => ['code' => -31001, 'message' => ['ru' => 'Сумма не совпадает']], 'id' => $id]);
        exit;
    }

    echo json_encode(['result' => ['allow' => true], 'id' => $id]);
    exit;
}

if ($method === 'PerformTransaction') {
    $paymeId = $params['id'];
    // Найти платёж по payme_id и подтвердить
    $payment = findPaymentByPaymeId($paymeId);
    if ($payment && !$payment->isPaid()) {
        $payment->setPaid('Y');
        $payment->save();
    }
    echo json_encode(['result' => [
        'transaction'  => $paymeId,
        'perform_time' => time() * 1000,
        'state'        => 2,
    ], 'id' => $id]);
    exit;
}

Остальные методы реализуются по тому же шаблону. В CreateTransaction важно вернуть create_time и state = 1. А в CancelTransaction — проверить, был ли уже выполнен Perform, и вернуть корректный state (-1 или -2).

Валюта и пересчёт тийинов

Payme принимает только узбекские сумы, а сумма передаётся в тийинах (1 UZS = 100 тийинов). Если цены в магазине в валюте (USD/EUR), пересчет делаем по курсу ЦБ РУ, кешируя на 1 час.

$amountTiyin = (int)round($orderPriceUsd * $uzsPerUsd * 100);

Ошибка в округлении на 1 тийин приведёт к отказу в CheckPerformTransaction — поэтому проверяем точное совпадение.

Тестирование

Тестовый эндпоинт: https://checkout.test.paycom.uz/. Тестовые ключи выдаются отдельно от боевых. Обязательно проверяем CancelTransaction на разных стадиях — поведение меняется. В среднем отладка занимает 1–2 дня.

Какие этапы включает интеграция Payme?

1. Проектирование и аналитика — уточняем валюту, способы расчёта, логику возвратов.
2. Разработка JSON‑RPC сервера — реализуем все 6 методов с идемпотентностью и логированием.
3. Интеграция с модулем Sale — привязываем платежи к заказам Битрикс, обновляем статусы и флаги оплаты.
4. Пересчёт валют — если магазин работает в USD/EUR, добавляем кешируемый конвертер в UZS.
5. Тестирование — ручные и автоматические тесты для каждого сценария (успех, отмена, дубль, ошибка).
6. Документация и обучение — описание эндпоинтов, примеры запросов/ответов, инструкция для менеджеров.
7. Поддержка после запуска — 2 недели мониторинга и оперативного исправления.

Что входит в работу

• Реализация JSON-RPC сервера со всеми 6 методами и идемпотентностью.
• Интеграция с модулем Sale Битрикс: создание платёжной системы, привязка к заказам.
• Валютный пересчёт с кешированием курса ЦБ РУ.
• Тестирование в тестовой среде Payme и на боевых данных.
• Документация по эндпоинтам и процедуре эксплуатации.
• Обучение менеджеров и администраторов.

Почему это выгодно

Использование Payme увеличивает конверсию среди узбекских покупателей в 2–3 раза. По сравнению с редиректными шлюзами, прямая интеграция через JSON-RPC снижает время обработки платежа с 5-10 секунд до 1-2 секунд. Наш опыт показывает, что магазин окупает интеграцию за первый месяц работы с регионом; средняя экономия на возвратах составляет до 5 000 000 UZS ежемесячно.

Закажите интеграцию Payme для вашего магазина на 1С-Битрикс — мы гарантируем соответствие спецификации Payme и запуск в течение 1-2 недель. Свяжитесь с нами, чтобы получить предварительную оценку за один рабочий день.

Как избежать типичных ошибок при подключении платёжных систем на 1С-Битрикс

Самая частая ошибка при интеграции — забыть про callback. Покупатель оплатил заказ, деньги списались, а статус в b_sale_order не обновился: менеджер видит «Ожидание оплаты» и начинает звонить клиенту. Причина — неправильный URL в настройках шлюза или обработчик, падающий с 500 при нестандартной структуре ответа. Мы предлагаем услуги по подключению платёжных систем на 1С-Битрикс с полным тестированием всех сценариев: успешная оплата, отказ, таймаут, частичный возврат, повторный callback.

Почему callback-уведомления критичны?

Каждый платёжный шлюз присылает уведомление на ваш сервер. Если обработчик не гарантирует идемпотентность — двойной вызов приведёт к двойному списанию. Мы всегда реализуем проверку по ID уведомления (external_id) и блокировку повторной обработки в \Bitrix\Sale\Order. Также критично настроить URL callback в личном кабинете агрегатора — /bitrix/tools/sale_ps_result.php для штатного модуля. Если используете кастомный обработчик, проверяем, что он отдаёт HTTP 200 даже при ошибке параметров (шлюз не должен повторять запрос бесконечно).

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

// Получаем данные уведомления
$data = Application::getInstance()->getContext()->getRequest()->toArray();
// Проверяем подпись (зависит от агрегатора)
if (!checkSignature($data, 'SECRET_KEY')) {
    die('FAIL');
}
// Ищем заказ по внешнему ID
$order = Order::loadByExternalId((int)$data['order_number']);
if ($order && $order->isPaid() === false) {
    $order->setField('PAYED', 'Y');
    $order->save();
}
echo 'OK';

Как выбрать платёжный агрегатор для 1С-Битрикс?

Выбор агрегатора зависит от географии покупателей, среднего чека и потребности в рассрочке. Для России базовый набор — ЮKassa (все основные методы, фискализация из коробки) и CloudPayments (виджет на странице без редиректа, Apple Pay). Если работаете с крупными корпоративными клиентами — добавьте Сбербанк (SberPay, СБП). Для международных продаж — Stripe или PayPal. Мы часто используем двухуровневую схему: основной агрегатор + резервный (автопереключение при падении).

Какие платёжные агрегаторы и способы оплаты мы используем

ЮKassa

Один договор — все основные способы: карты Visa/MasterCard/МИР, ЮMoney, SberPay, интернет-банки, рассрочка. Фискализация по 54-ФЗ из коробки (через модуль sale). Штатный обработчик /bitrix/modules/sale/handlers/paysystem/yandexpay/ покрывает базовые сценарии. Для холдирования (двухстадийная оплата), подписок или сплит-платежей — кастомная интеграция через YooKassa API v3. Callback настраиваем на /bitrix/tools/sale_ps_result.php, парсим notification и обновляем \Bitrix\Sale\Order через setField('PAYED', 'Y').

CloudPayments

Заточен на конверсию: виджет оплаты прямо на странице чекаута, без редиректа на внешний домен. Покупатель не уходит с сайта — процент отказов на этапе оплаты падает. Поддерживает рекуррентные платежи (токенизация карты через cryptogram), Apple Pay и Google Pay. 3D Secure с интеллектуальной маршрутизацией — запрашивается только при высоком риске фрода. Интеграция с Битрикс — через REST API CloudPayments и кастомный обработчик в модуле sale.

Тинькофф Оплата

API-интеграция через TinkoffPaymentAPI (готовый модуль или ручная реализация). QR-код для оплаты через приложение, рассрочка «Тинькофф Кредит» — критично для дорогих товаров. Частичные возвраты через метод Cancel — без звонков в банк, всё из админки Битрикс.

Сбербанк (SberPay и СБП)

SberPay — оплата по push-уведомлению или QR, СБП — комиссия 0.4–0.7% против 1.5–2.5% по картам. На объёме это ощутимая экономия. Холдирование через API registerPreAuth / deposit. Учитываем, что для SberPay требуется подписание отдельного договора с банком.

Apple Pay и Google Pay

Оплата в два касания, без ввода данных карты. Подключаются через агрегатор (ЮKassa, CloudPayments, Тинькофф). Важные нюансы:

• Apple Pay требует верификации домена: файл apple-developer-merchantid-domain-association в /.well-known/. Без него кнопка не появится.
• Размещение кнопок строго по гайдлайнам Apple и Google — иначе отказ в ревью.
• Фоллбэк на стандартную форму оплаты, если устройство не поддерживает бесконтактную оплату.

Рассрочка, BNPL и работа с 54-ФЗ

Если средний чек от 30 000 ₽ и конверсия проседает — рассрочка снимает ценовой барьер. Мы подключаем:

• Тинькофф Рассрочка (3–24 месяца)
• Покупай со Сбером
• Мокка / Долями — BNPL: 4 платежа, 0% для покупателя

Интеграция: виджет с расчётом ежемесячного платежа на карточке товара («от 2 500 ₽/мес»), передача данных заказа в банк через API, обработка статусов (одобрение, отказ, ожидание документов) в обработчиках OnSaleStatusOrder.

Фискализация по 54-ФЗ — обязательное требование. Штраф за отсутствие чека — до 100% от суммы расчёта. В соответствии с Федеральным законом № 54-ФЗ кассовый чек должен быть отправлен покупателю в электронной форме. Подключаем АТОЛ Онлайн, Orange Data, Модуль.Касса, Эвотор, Штрих-М. Настройка в Битрикс — раздел «Кассы» в модуле sale:

• Ставка НДС, предмет и способ расчёта — ошибка в любом поле может привести к штрафу при проверке.
• Чеки при предоплате и частичной оплате (два чека: при оплате и при отгрузке).
• Чеки возврата при отмене через \Bitrix\Sale\Cashbox\Cashbox::addChecks().
• Мониторинг: если чек не ушёл — алерт менеджеру.

При торговле обувью, одеждой, парфюмерией обязательна передача кодов маркировки в чеке. Интеграция с «Честный ЗНАК», сканирование DataMatrix при сборке заказа, автоматический вывод из оборота при продаже через \Bitrix\Catalog\Product\Marking.

Сопровождение платежей: возвраты, мультивалюта, безопасность

Возвраты

Полный и частичный возврат без звонков в банк — через API агрегатора (refund / cancel). Чек возврата формируется автоматически, обновляется статус заказа, пересчитывается сумма, уведомляется покупатель. Сроки: электронные кошельки и СБП — 1–3 дня, банковская карта — до 30 рабочих дней (зависит от банка-эмитента).

Мультивалюта

Типы цен в b_catalog_price для каждой валюты, курсы через API ЦБ (\Bitrix\Currency\CurrencyManager::updateCBRFRates()) или ручной ввод. Конвертация на уровне каталога — покупатель видит цены в своей валюте. Для приёма долларов/евро подключаем Stripe, PayPal. Учитываем комиссии за конвертацию при расчёте маржинальности.

Безопасность

Данные карт обрабатываются на стороне сертифицированного шлюза (PCI DSS) — номер карты никогда не проходит через ваш сервер. Антифрод на уровне агрегатора. Логирование всех событий в b_sale_order_change для аудита. Мониторинг аномалий: скачок транзакций, нетипичная география — алерт.

Как мы работаем и ориентировочные сроки

1. Анализ — какие способы оплаты нужны, рынки, объём транзакций, текущий агрегатор.
2. Подбор решений — иногда два агрегатора лучше одного: ЮKassa как основной, CloudPayments как резерв — при падении одного трафик уходит на второй.
3. Интеграция — тестируем каждый сценарий: успешная оплата, отказ 3DS, таймаут шлюза, двойной callback, частичный возврат.
4. Фискализация — онлайн-касса, проверка корректности чеков на тестовых заказах.
5. Мониторинг — алерты при сбоях шлюза, дашборд конверсии на этапе оплаты.

Что входит в работу

• Полная настройка выбранных платёжных систем в 1С-Битрикс: модули, обработчики, callback, тестирование.
• Документация по интеграции (схема работы шлюзов, описание обработчиков, логи).
• Обучение вашего менеджера работе с платёжными модулями и возвратами.
• Техническая поддержка на этапе запуска и первые 2 недели эксплуатации.
• Мониторинг — настраиваем алерты на ошибки и падение конверсии.

Все работы выполняются сертифицированными разработчиками 1С-Битрикс. Гарантируем работоспособность каждого сценария. Для быстрой оценки вашего проекта получите консультацию — просто оставьте заявку на сайте. Закажите интеграцию платёжных систем под ключ с фискализацией и защитой данных. Свяжитесь с нами, чтобы подобрать оптимальное решение для вашего бизнеса — мы поможем с выбором агрегатора и реализуем полный цикл интеграции.