שילוב 1C-Bitrix עם Halyk Bank: מדריך טכני

בעת שילוב 1C-Bitrix עם Halyk Bank, מפתחים נתקלים לעיתים קרובות בשגיאות בעיבוד הודעות callback ובשמירה לא נכונה של אסימוני גישה (access tokens). הדבר מוביל לאובדן הזמנות ולשבירה של שרשורי תשלום. Callbacks מגיעים לעיתים קרובות באיחור או לא מגיעים כלל, מה שגורם לחיובים כפולים ולחוסר שביעות רצון של לקוחות. לצוות שלנו יש ניסיון של 5+ שנים ו-50+ שילובים מוצלחים עם Halyk Bank. הבה נבחן כיצד להגדיר כראוי את האינטראקציה ולהימנע ממלכודות נפוצות.

Halyk Bank—הבנק הגדול בקזחסטן—מספק סליקת אינטרנט באמצעות שער התשלומים Halyk eCommerce (לשעבר HomeBank). השער מקבל ויזה, מאסטרקארד, אמריקן אקספרס ותשלומים דרך אפליקציית HalykPay הניידת. השילוב עם Bitrix מיושם באמצעות מודול תשלום סטנדרטי עם מטפלי PHP. ניסיון השנים שלנו בפיתוח עם Bitrix ועשרות פרויקטי שילוב מוצלחים עם שערי תשלום, כולל Halyk Bank, מבטיחים טיפול נכון בכל הסטטוסים וההחזרים. אנו מחזיקים בהסמכות Bitrix ובעלי ניסיון רב בפיתוח מודולים.

מאמר זה מכסה ביסודיות את ארכיטקטורת השילוב, מספק דוגמאות קוד ליצירת תשלומים וטיפול ב-callbacks, ומציע המלצות לשגיאות טיפוסיות. תלמדו כיצד להגדיר תשלומים דו-שלביים והחזרים, וכיצד לשמור אסימונים במטמון לפעולה אמינה.

שילוב 1C-Bitrix עם Halyk Bank: מבחירת שיטה ועד עיבוד תשלומים

באיזו שיטת חיבור כדאי לבחור?

Halyk Bank מספק מספר אפשרויות חיבור: Halyk eCommerce (הפנייה), Halyk API (עיבוד ישיר) ו-HalykPay. להלן השוואה לפי פרמטרים מרכזיים:

עבור 90% מהחנויות המקוונות הקזחיות, סכמת ההפנייה היא האופטימלית. היא מסירה את האחריות לאחסון נתוני כרטיס ומאיצה את זמן היציאה לשוק פי 2 בהשוואה לעיבוד ישיר. החיסכון בעמלת הסליקה יכול להגיע ל-0.5% מהמחזור. סכמת ההפנייה מהירה פי 2 ליישום מאשר עיבוד ישיר, וחוסכת עד 0.5% מהמחזור בעמלות.

הגדרת סכמת ההפנייה

הפנייה לטופס התשלום של הבנק פוטרת את החנות מאחריות לאחסון נתוני כרטיס—אין צורך לעבור ביקורת PCI DSS. זמן היישום מופחת ב-40-50% בהשוואה לעיבוד ישיר. בנוסף, סכמה זו מפשטת את התמיכה והעדכונים של מודול התשלום.

ארכיטקטורת השילוב: שלב אחר שלב

1. קבלו מזהה טרמינל, client_id, client_secret וכתובות שער מ-Halyk Bank. לבדיקות, השתמשו בסביבת הבדיקה בכתובת https://test.epayment.halykbank.kz כדי לדמות תשלומים במצב בדיקה של Halyk Bank.
2. יישמו קבלת אסימון באמצעות אישורי לקוח OAuth2.
3. צרו חשבונית עם הפרמטרים הנדרשים (סכום, מזהה הזמנה, כתובות callback).
4. טפלו בהודעות callback על ידי אימות עם בקשת API נוספת.
5. הגדירו שמירת אסימונים במטמון ולוגיקת רענון.

קבלת אסימון גישה:

$tokenUrl = 'https://epayment.halykbank.kz/api/public/v1/auth/token';
$ch = curl_init($tokenUrl);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/x-www-form-urlencoded',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'grant_type' => 'client_credentials',
    'client_id' => $clientId,
    'client_secret' => $clientSecret,
    'scope' => 'webapi usermanagement email_send verification statement statistics payment',
    'terminal' => $terminal,
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$tokenData = json_decode(curl_exec($ch), true);
$accessToken = $tokenData['access_token'];

יצירת תשלום:

$orderId = $payment->getOrder()->getId();
$amount = $payment->getSum(); // в тенге

$invoiceData = [
    'amount' => $amount,
    'currency' => 'KZT',
    'terminal' => $terminal,
    'invoiceId' => $orderId,
    'description' => 'Заказ №' . $orderId,
    'language' => 'rus',
    'postLink' => $callbackUrl,
    'failurePostLink' => $callbackUrl,
    'backLink' => $returnUrl,
    'failureBackLink' => $failUrl,
];

$ch = curl_init('https://epayment.halykbank.kz/api/public/v1/invoices/create');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $accessToken,
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($invoiceData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$invoice = json_decode(curl_exec($ch), true);
$invoiceId = $invoice['id'];
$paymentUrl = 'https://epayment.halykbank.kz/pay/invoices/' . $invoiceId;
// Редирект покупателя на $paymentUrl

טיפול בהודעות callback

Halyk שולח POST אל terminal בעת תשלום או שגיאה:

$rawBody = file_get_contents('php://input');
$data = json_decode($rawBody, true);
$invoiceId = $data['id']; // ID счёта Halyk
$orderId = $data['invoiceId']; // наш orderId
$txStatus = $data['status']; // 'CHARGED', 'DECLINED', 'CANCELLED'

// Верификация: запросить статус через API
$verification = $this->httpGet(
    'https://epayment.halykbank.kz/api/public/v1/check-transaction',
    ['invoiceId' => $orderId],
    ['Authorization: Bearer ' . $accessToken]
);

if ($verification['status'] === 'CHARGED') {
    $order = \Bitrix\Sale\Order::loadByAccountNumber($orderId);
    // setPaid('Y'), save()
}

http_response_code(200);

סטטוסים שעשויים להגיע:

הגדרת תשלומים דו-שלביים

Halyk תומך בסכמת "אישור + אישור סופי":

// Создать инвойс с параметром "preAuth": true
$invoiceData['preAuth'] = true;

// После обработки заказа — подтвердить списание
$confirmData = [
    'invoice_id' => $halykInvoiceId,
    'amount' => $amount,
];
$this->httpPost('https://epayment.halykbank.kz/api/public/v1/confirm', $confirmData, $headers);

// Или отмена холда
$this->httpPost('https://epayment.halykbank.kz/api/public/v1/cancel', ['invoice_id' => $halykInvoiceId], $headers);

עיבוד החזרים

$refundData = [
    'invoice_id' => $halykInvoiceId,
    'amount' => $refundAmount,
    'reason' => 'Возврат по заказу',
];

$this->httpPost(
    'https://epayment.halykbank.kz/api/public/v1/refund',
    $refundData,
    ['Authorization: Bearer ' . $accessToken, 'Content-Type: application/json']
);

רענון אסימון הגישה

לאסימון הגישה יש תוחלת חיים מוגבלת. אנו ממליצים ליישם שמירה במטמון ורענון אוטומטי. בעת קבלת HTTP 401, בקשו מחדש את האסימון ונסו שוב את הבקשה. שמרו את שני מזהי החשבונית: client_id (שלכם) ו-client_secret (הפנימי של Halyk)—הם נדרשים להחזרים ולאימות.

טעויות נפוצות של מתחילים וכיצד להימנע מהן

מתחילים לעיתים קרובות מדלגים על אימות callback באמצעות בקשת API נוספת, מה שמוביל לאישורים מזויפים. הטעות השנייה היא אי-שמירת האסימון במטמון: בקשת אסימון חדש בכל קריאה מגדילה את זמן התגובה ב-20-30%. השלישית היא אי-טיפול בסטטוס AUTHENTICATED בסכמות דו-שלביות, מה שגורם לכסף להיות מוחזק אך לא מחויב. הניסיון שלנו מראה שבעיות אלו מתרחשות ב-70% מהפרויקטים בתחילת הדרך.

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

• ניתוח לוגיקת התשלום הנוכחית ב-Bitrix
• תכנון סכמת השילוב (הפנייה או ישיר)
• פיתוח מודול עם מטפלים לאסימון, חשבונית ו-callback
• הגדרת תשלומים דו-שלביים (במידת הצורך)
• יישום החזרים ושמירת אסימונים במטמון
• בדיקות בסביבות בדיקה וייצור
• תיעוד והדרכה לצוות שלכם
• תמיכה באחריות ל-30 יום

בנוסף, אנו מציעים שילוב Halyk Bank עם 1C-Bitrix במפתח מלא, כולל ניהול פרויקט מלא. עלות שילוב טיפוסית נעה בין $1,500 ל-$3,000 בהתאם למורכבות.

לוח זמנים לפיתוח

לוח הזמנים הכולל—3 עד 6 ימי עבודה. התמחור מחושב באופן אישי לאחר הערכת הפרויקט. קבלו ייעוץ—צרו קשר כדי שנציע את הפתרון הטוב ביותר לחנות שלכם. הזמינו שילוב—נבצע ביקורת לחנות שלכם ונציע פתרון אופטימלי. העריכו את הפרויקט שלכם ביום אחד—כתבו לנו.

תיעוד רשמי של API של Halyk Bank