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

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

Ми не раз стикалися з ситуацією: інтернет-магазин на Бітрікс втрачає до 30–40% замовлень тільки через те, що не приймає Payme — головний платіжний інструмент Узбекистану з більш ніж 10 млн активних користувачів. Офіційного модуля для Бітрікс немає, і тут потрібен кастомний JSON‑RPC обробник. Без нього конверсія в регіоні залишається низькою, а клієнти йдуть до конкурентів. Пряма інтеграція через JSON-RPC в 3 рази швидша за редиректні шлюзи, що підвищує задоволеність клієнтів. Ми, команда з 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 секунд. Наш досвід показує, що магазин окупає інтеграцію за перший місяць роботи з регіоном. Вартість інтеграції розраховується індивідуально. Конверсія зростає на 40-60%, а середній чек збільшується на 15%.

Замовте інтеграцію 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 навіть при помилці параметрів (шлюз не повинен повторювати запит нескінченно). Через некоректний callback втрачається до 30% успішних оплат — покупець платить, але статус не оновлюється, і ви не отримуєте гроші.

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, Google Pay). Якщо працюєте з великими корпоративними клієнтами — додайте Ощадбанк (SberPay, СБП). Для міжнародних продажів — Stripe або PayPal. Ми часто використовуємо дворівневу схему: основний агрегатор + резервний (автоперемикання при падінні). CloudPayments забезпечує на 15–25% більше успішних оплат за рахунок віджету без редиректу — покупець не йде з сайту.

Які платіжні агрегатори та способи оплати ми використовуємо

ЮKassa

Один договір — всі основні способи: картки Visa/MasterCard/МИР, ЮMoney, SberPay, інтернет-банки, розстрочка. Фіскалізація за 54-ФЗ з коробки (через модуль sale). Штатний обробник /bitrix/modules/sale/handlers/paysystem/yandexpay/ покриває базові сценарії. Для холдування (двостадійна оплата), підписок або спліт-платежів — кастомна інтеграція через 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 та кастомний обробник.

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

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

Ощадбанк (SberPay та СБП)

SberPay — оплата за push-сповіщенням або QR, СБП — комісія нижча порівняно з картками. На обсязі це відчутна економія. Холдування через API registerPreAuth / deposit. Враховуємо, що для SberPay потрібне підписання окремого договору з банком.

Apple Pay та Google Pay

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

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

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

Якщо середній чек великий і конверсія просідає — розстрочка знімає ціновий бар'єр. Ми підключаємо:

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

Інтеграція: віджет з розрахунком щомісячного платежу на картці товару («від суми на місяць»), передача даних замовлення в банк через API, обробка статусів (схвалення, відмова, очікування документів) в обробниках OnSaleStatusOrder.

Фіскалізація за 54-ФЗ — обов'язкова вимога. Штраф за відсутність чека — до значної суми. Відповідно до Федерального закону № 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. Моніторинг — алерти при збоях шлюзу, дашборд конверсії на етапі оплати.

Як підібрати оптимальний платіжний агрегатор?

Вибір агрегатора залежить від специфіки бізнесу: обсягу продажів, географії клієнтів, необхідності у розстрочці або рекурентних платежах. Ми допомагаємо проаналізувати ваші потреби та обрати найкраще рішення. Маємо понад 7 років досвіду в інтеграції платіжних систем на Бітрікс, реалізували більше 50 проектів. Замовте консультацію — ми розповімо про плюси та мінуси кожного варіанту.

Що входить в роботу

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

Всі роботи виконуються сертифікованими розробниками 1С-Бітрікс. Гарантуємо працездатність кожного сценарію. Для швидкої оцінки вашого проекту залиште заявку на сайті або зв'яжіться з нами — підберемо оптимальне рішення для вашого бізнесу.