שילוב 1C-Bitrix עם Payme (אוזבקיסטן) – מדריך JSON-RPC

אינטגרציה של 1C-Bitrix עם Payme (אוזבקיסטן)

נתקלנו שוב ושוב במצבים שבהם חנות מקוונת על Bitrix מאבדת 30–40% מההזמנות רק בגלל שהיא לא מקבלת Payme — כלי התשלום המוביל באוזבקיסטן עם למעלה מ-10 מיליון משתמשים פעילים. אין מודול רשמי ל-Bitrix, ולכן נדרש handler מותאם אישית של JSON‑RPC. בלעדיו, ההמרה באזור נשארת נמוכה ולקוחות פונים למתחרים. אנחנו, צוות עם ניסיון של למעלה מ-7 שנים בפיתוח Bitrix ויותר מ-50 אינטגרציות תשלום, נפרק כיצד לבנות אינטגרציה נכונה עם idempotency מובטח וטיפול נכון במטבע.

כיצד פועל ה-Subscribe API של Payme

Payme לא משתמש בהפניות (redirects) — במקום זאת, שרת Payme קורא לשרת שלך באמצעות פרוטוקול JSON‑RPC. החנות מיישמת שש שיטות חובה, כל אחת חייבת להגיב תוך 1–2 שניות. הפרות תזמון גורמות לתשלומים להיתקע.

ה-endpoint שלך של JSON‑RPC (לדוגמה, local/api/payme.php) מעבד את כל השיטות הללו, בודק הרשאות באמצעות Basic Auth, ומחזיר מבנים מוגדרים בקפדנות.

למה Idempotency חשוב ואיך להשיג אותו

אם Payme שולח CreateTransaction פעמיים, אותו תשלום עלול להתחייב פעמיים. אנחנו פותרים זאת עם טבלה ייעודית b_payme_transactions, שבה המפתח הראשי הוא payme_id. בקשה כפולה עם אותו payme_id מחזירה את העסקה הקיימת במקום ליצור חדשה. זה מונע חיובים כפולים ועומד בדרישות ה-API של Payme (ראה תיעוד 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
);

מצבים: 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 — בוטל בשלבים שונים.

שגיאות נפוצות ופתרונות

יישום שרת ב-Bitrix (מקרה מבחן)

נקודת הכניסה היא קובץ PHP נפרד, בלתי תלוי בחלק הציבורי. הוא מטפל בכל שש השיטות. להלן קטע המפתח עבור -32504:

<?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;
}

השיטות הנותרות פועלות לפי אותו דפוס. ב-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 הנכון (-1 או -2).

מטבע והמרת טיין

Payme מקבל רק סומים אוזבקיים, וסכומים מועברים בטיינים (1 UZS = 100 טיינים). אם מחירי החנות במטבע זר (USD/EUR), אנו ממירים לפי שער הבנק המרכזי של אוזבקיסטן, עם קאשינג לשעה.

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

שגיאת עיגול בפער של אחד תגרום לדחייה ב-Perform — לכן התאמה מדויקת היא קריטית.

בדיקות

Endpoint לבדיקות: state. מפתחות בדיקה מונפקים בנפרד ממפתחות ייצור. הקפד לבדוק $amountTiyin = (int)round($orderPriceUsd * $uzsPerUsd * 100); בשלבים שונים — ההתנהגות משתנה. בממוצע, איתור באגים אורך 1–2 ימים.

מה כולל תהליך האינטגרציה

1. עיצוב וניתוח — הבהרת מטבע, שיטות סליקה, לוגיקת החזרים.
2. פיתוח שרת JSON‑RPC — יישום כל 6 השיטות עם idempotency ולוגינג.
3. אינטגרציה עם מודול ה-Sale של Bitrix — קישור תשלומים להזמנות, עדכון סטטוסים ודגלי תשלום.
4. המרת מטבע — אם החנות פועלת ב-USD/EUR, הוסף ממיר עם קאשינג ל-UZS.
5. בדיקות — בדיקות ידניות ואוטומטיות לכל תרחיש (הצלחה, ביטול, כפילות, שגיאה).
6. תיעוד והדרכה — תיאורי endpoint, דוגמאות בקשה/תגובה, הוראות למנהלים.
7. תמיכה לאחר השקה — שבועיים של ניטור ותיקונים מהירים.

מה כלול בעבודה

• יישום שרת JSON-RPC עם כל 6 השיטות ו-idempotency.
• אינטגרציה עם מודול ה-Sale של Bitrix: יצירת מערכת תשלום, קישור להזמנות.
• המרת מטבע עם קאשינג לשער הבנק המרכזי.
• בדיקות בסביבת הבדיקה של Payme ועל נתונים חיים.
• תיעוד על endpoints ונהלי פעולה.
• הדרכה למנהלים ומנהלי מערכת.

למה זה משתלם

אינטגרציה עם Payme מגבירה את ההמרה בקרב לקוחות אוזבקיים פי 2–3. בהשוואה לשערי redirect, אינטגרציית JSON-RPC ישירה מקצרת את זמן עיבוד התשלום מ-5–10 שניות ל-1–2 שניות. הניסיון שלנו מראה שחנות מחזירה את עלות האינטגרציה בתוך החודש הראשון לפעילות באזור; החיסכון הממוצע בהחזרים מגיע עד 5,000,000 UZS בחודש.

הזמן אינטגרציית Payme לחנות ה-1C-Bitrix שלך — אנו מבטיחים עמידה במפרט Payme והשקה תוך 1–2 שבועות. צור קשר כדי לקבל הערכה ראשונית תוך יום עסקים אחד.