הגדרת BayarCash ב-Laravel בדרך הנכונה

אם אתם בונים SaaS לשוק המלזאי, תזדקקו בסופו של דבר ל-FPX. BayarCash הוא בחירה נפוצה.

ה-SDK אינו הבעיה. הבעיה היא הארכיטקטורה שלכם. אם תקראו ל-SDK מתוך controller או תכתבו קודי סטטוס (status codes) באופן קשיח בתוך ה-views שלכם, תיתקלו בבעיות בסביבת הייצור (production).

הטמעתי את BayarCash בשלוש אפליקציות Laravel שונות. הנה התבנית שעובדת בכל פעם.

מושגי מפתח שכדאי לשלוט בהם

  • Portal: הגדרת ה-checkout של הסוחר שלכם. השתמשו ב-portal_key.
  • API Token: מאמת את הקריאות היוצאות שלכם.
  • Secret Key: חותם על ה-payloads שלכם ומאמת webhooks. שמרו עליו במקום בטוח.
  • Payment Intent: אתם שולחים בקשת חיוב (charge), מקבלים URL ומבצעים הפניה (redirect) למשתמש.
  • Channel: השתמשו תמיד בקבועים (constants) של ה-SDK במקום במספרים גולמיים.

בנו את הקוד שלכם בצורה טובה

קוד ה-domain שלכם לעולם לא אמור לראות payload גולמי של BayarCash. אתם זקוקים לשלוש שכבות:

  • A thin client wrapper: מטפל בהגדרות (config) ומספק מתודות עם טיפוסים (typed methods).
  • A gateway: מממש interface ו"מדבר" בשפת ה-domain שלכם.
  • A factory: בוחר את ה-gateway הפעיל כך שתוכלו להחליף את BayarCash ב-Stripe בקלות.

קישור (Binding) של Fake Gateway

אם אינכם מספקים API token, קשרו (bind) Fake provider בתוך ה-service container שלכם. זה מאפשר לבדיקות (tests) שלכם לרוץ ללא רשת ומאפשר לגרסאות המקומיות (local builds) שלכם לרוץ ללא חיוב פעיל.

שיטות עבודה מומלצות ל-Webhook

ה-webhook הוא מקור האמת שלכם. עקבו אחר הכללים הללו כדי להימנע מ"סערה" בסביבת הייצור:

  • CSRF Exempt: נתיב ה-webhook שלכם חייב לעקוף את הגנת ה-CSRF.
  • Verify Signatures: תמיד אמתו את החתימה לפני שאתם עושים כל דבר אחר.
  • The 200 Rule: ברגע שאימתם את החתימה, החזירו תגובת 2xx.
  • Avoid Retries: אם תחזירו שגיאת 500, BayarCash ינסה לשלוח את ה-webhook שלכם שוב 40 פעמים. זה עלול להפיל את השרת שלכם. תעדו (log) שגיאות, אך עדיין החזירו 200.
  • Idempotency: ודאו שהלוגיקה שלכם יכולה לטפל באותו webhook פעמיים מבלי ליצור הזמנות כפולות.

רשימת בדיקה להצלחה

• השתמשו ב-order_number כמפתח קורלציה (correlation key). שמרו עליו מתחת ל-30 תווים. • שמרו רשומה מקומית במצב "ממתין" (pending) לפני שאתם מבצעים הפניה למשתמש. • השתמשו ב-callback מסוג server-to-server כמקור הסמכות העיקרי שלכם. • השתמשו ב-return URL כרשת ביטחון לצורך התאמות (reconciliation). • מיפו קודי סטטוס מסוג integer לתוך ה-Enums שלכם באופן מיידי.

אינטגרציות תשלום נוגעות בכסף אמיתי. בדקו את אימות החתימה ואת האידמפוטנטיות שלכם יותר מכל דבר אחר.

מקור: https://dev.to/nasrulhazim/setting-up-bayarcash-fpx-in-laravel-the-right-way-4b2n