שילוב תשלומי Kapital Bank עם 1C-Bitrix

שילוב תשלומי Kapital Bank עם 1C-Bitrix

אם חנות ה-1C-Bitrix שלך אינה מקבלת כרטיסי Kapital Bank — הבנק הגדול ביותר באזרבייג'ן עם נתח שוק של למעלה מ-40% בתשלומים מקוונים — אתה מפסיד עד 30% מהקונים. שילוב בנק זה אינו רק הוספת אמצעי תשלום; הוא מגביר אמון: לוגו מוכר בדף התשלום משפר את שיעור ההמרה ב-15–20%. אנו מפתחים מודולי תשלום עבור Bitrix מאז 2013 והשלמנו למעלה מ-50 פרויקטים של שילוב מערכות תשלום. תוך 3–5 ימים אנו מחברים את Kapital Bank HPP כך שלקוחותיך מאזרבייג'ן יוכלו לשלם עם Visa ו-Mastercard. כל מה שאנו צריכים ממך הוא ה-Merchant ID והמפתח הסודי; אנו מטפלים בשאר. קבל ייעוץ תוך יום. שילוב HPP בסיסי מתחיל מ-$350 (חנות סטנדרטית), עם תמיכה בהחזרים מ-$600.

שיטות חיבור ל-Kapital Bank

הבנק מציע שתי אפשרויות: HPP (Hosted Payment Page) ו-Direct API. HPP היא השיטה הסטנדרטית עבור 95% מהסוחרים: הלקוח מועבר לדף הבנק, מזין את פרטי הכרטיס, והאתר מקבל קריאת חוזר (callback) עם התוצאה. שיטה זו אינה דורשת הסמכת PCI DSS — האבטחה מטופלת כולה על ידי הבנק. Direct API כולל העברה ישירה של פרטי כרטיס דרך ה-API, מה שמחייב PCI DSS ונמצא בשימוש נדיר (אפליקציות מובייל, תרחישים לא סטנדרטיים). עבור חנות טיפוסית, HPP מהיר פי 5 ליישום וזול ב-30% מ-Direct API, ללא אילוצים בירוקרטיים נוספים. עלות שילוב HPP נמוכה ב-30–40%, ושיעור ההמרה גבוה יותר בשל האמון בדף הבנק.

כיצד פועל שילוב HPP עם Kapital Bank

1. הלקוח בוחר תשלום בכרטיס באתר.
2. המערכת יוצרת בקשת XML עם הסכום (בקפיק: 1 AZN = 100 קפיק) ושולחת אותה לנקודת הקצה REST של הבנק באמצעות cURL עם הצפנת TLS 1.2.
3. הבנק משיב עם OrderId ו-SessionId — אלה משמשים לבניית כתובת ה-URL להפניה ל-HPP.
4. הלקוח מזין את פרטי הכרטיס בדף הבנק, המוגן באימות 3DSecure.
5. בעת הצלחה, הבנק שולח קריאת חוזר ל-ApproveURL — המטפל שלנו מאמת את התשובה באמצעות checksum (HMAC-SHA256) ומעדכן את סטטוס ההזמנה לאחר קריאת GetOrderStatus נוספת כדי למנוע הזמנות כפולות.

אנו מיישמים מטפל מותאם אישית המבוסס על \Bitrix\Sale\PaySystem\ServiceHandler עם המתודות initiatePay(), processRequest() ו-refund(). הפרטים נמצאים במבנה הבקשה להלן.

מבנה הבקשה ל-API של הבנק

בעת התחלת תשלום, נשלחת בקשת POST לנקודת הקצה:

• בדיקות: https://tstpg.kapitalbank.az/api/order/
• ייצור: https://pg.kapitalbank.az/api/order/

הגוף — XML בקידוד UTF-8 (ללא BOM):

<TKKPG>
  <Request>
    <Operation>CreateOrder</Operation>
    <Language>RU</Language>
    <Order>
      <OrderType>Purchase</OrderType>
      <Merchant>MERCHANT_ID</Merchant>
      <Amount>15000</Amount>
      <Currency>944</Currency><!-- AZN = 944 по ISO 4217 -->
      <Description>Заказ №12345</Description>
      <ApproveURL>https://site.az/payment/success/</ApproveURL>
      <CancelURL>https://site.az/payment/cancel/</CancelURL>
      <DeclineURL>https://site.az/payment/fail/</DeclineURL>
    </Order>
  </Request>
</TKKPG>

התשובה מכילה את <TKKPG> <Request> <Operation>CreateOrder</Operation> <Language>RU</Language> <Order> <OrderType>Purchase</OrderType> <Merchant>MERCHANT_ID</Merchant> <Amount>15000</Amount> <Currency>944</Currency><!-- AZN = 944 по ISO 4217 --> <Description>Заказ №12345</Description> <ApproveURL>https://site.az/payment/success/</ApproveURL> <CancelURL>https://site.az/payment/cancel/</CancelURL> <DeclineURL>https://site.az/payment/fail/</DeclineURL> </Order> </Request> </TKKPG> ו-OrderId, שעל בסיסם נוצרת כתובת ה-URL להפניה. לאחר התשלום, הבנק קורא ל-SessionId עם אותם פרמטרים. ב-ApproveURL אנו מבצעים בקשת processRequest() נוספת — ייתכן שהקריאה החוזרת תכיל חתימה, אך אנו מאמתים אותה באמצעות המפתח הסודי דרך HMAC-SHA256 כדי להבטיח אותנטיות.

טיפול בהחזרים

Kapital Bank תומך בשני סוגי החזרים:

• Reverse — החזר מלא ביום ביצוע העסקה.
• Refund — החזר חלקי או מאוחר.

המטפל מיישם את המתודה GetOrderStatus, הנקראת מלוח הבקרה של Bitrix כאשר סטטוס הזמנה משתנה ל-"Refund". בטבלת refund(), השדה b_sale_payment מאחסן את PS_INVOICE_ID מהבנק — הוא משמש לאתחול ההחזר.

טיפול בקריאות חוזרות חסרות

לפעמים התשלום עובר אך סטטוס ההזמנה אינו מתעדכן. סיבות נפוצות:

• כתובת ה-URL של הקריאה החוזרת אינה נגישה חיצונית (בדוק את הגדרות חומת האש ושרת האינטרנט, וודא תגובת HTTP 200).
• כתובת ה-IP של הבנק חסומה.
• בקשת ה-XML נשלחת בקידוד שגוי.

אנו תמיד מוסיפים רישום (logging) של בקשות נכנסות לנקודת הקצה של הקריאה החוזרת כדי לזהות במהירות את הבעיה. אנו גם מיישמים מפתחות idempotency כדי למנוע עיבוד כפול של הזמנות. בפרויקטים שלנו, לאחר בדיקות, זמן הסיום הוא 3–5 ימים, ובמהלך תקופה זו אנו מבטיחים פעולה יציבה של המטפל.

בדיקות ובעיות נפוצות