Интеграция 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 недель. Свяжитесь с нами, чтобы получить предварительную оценку за один рабочий день.