Правильне налаштування BayarCash у Laravel
Якщо ви розробляєте SaaS для малайзійського ринку, вам рано чи пізно знадобиться FPX. BayarCash — поширений вибір.
Проблема не в SDK. Проблема в архітектурі. Якщо ви викликаєте SDK безпосередньо з контролера або жорстко прописуєте коди статусів у представленнях (views), ви зіткнетеся з проблемами у продакшені.
Я впроваджував BayarCash у трьох різних Laravel-додатках. Ось патерн, який працює щоразу.
Key Terms To Master
- Portal: Конфігурація вашого мерчант-чекауту. Використовуйте
portal_key. - API Token: Автентифікує ваші вихідні запити.
- Secret Key: Підписує ваші корисні навантаження (payloads) та перевіряє вебхуки. Тримайте його в безпеці.
- Payment Intent: Ви надсилаєте запит на оплату, отримуєте URL і перенаправляєте користувача.
- Channel: Завжди використовуйте константи SDK замість "сирих" чисел.
Structure Your Code Well
Ваш доменний код ніколи не повинен бачити "сире" корисне навантаження BayarCash. Вам потрібні три рівні:
- Тонка обгортка клієнта (thin client wrapper): вона обробляє конфігурацію та надає типізовані методи.
- Шлюз (gateway): він реалізує інтерфейс і використовує мову вашого домену.
- Фабрика (factory): вона обирає активний шлюз, щоб ви могли легко замінити BayarCash на Stripe.
Binding a Fake Gateway
Якщо ви не надаєте API token, прив'яжіть Fake-провайдер у вашому сервіс-контейнері. Це дозволить вашим тестам працювати без мережі, а локальним збіркам — без активної оплати.
Webhook Best Practices
Вебхук — це ваше єдине джерело істини. Дотримуйтесь цих правил, щоб уникнути хаосу в продакшені:
- CSRF Exempt: Ваш маршрут вебхука має оминати захист CSRF.
- Verify Signatures: Завжди перевіряйте підпис перед виконанням будь-яких інших дій.
- The 200 Rule: Щойно ви перевірили підпис, поверніть відповідь 2xx.
- Avoid Retries: Якщо ви повернете помилку 500, BayarCash повторить запит до вашого вебхука 40 разів. Це може призвести до падіння сервера. Логуйте помилки, але все одно повертайте 200.
- Idempotency: Переконайтеся, що ваша логіка може обробити один і той самий вебхук двічі без створення дублікатів замовлень.
Checklist for Success
• Використовуйте order_number як ключ кореляції. Тримайте його довжиною до 30 символів.
• Збережіть локальний запис зі статусом "очікується" (pending) перед тим, як перенаправити користувача.
• Використовуйте server-to-server callback як основне джерело даних.
• Використовуйте return URL як страховку для звірки (reconciliation).
• Одразу зіставляйте цілочисельні коди статусів із власними Enum.
Інтеграція платежів стосується реальних грошей. Тестуйте перевірку підпису та ідемпотентність понад усе інше.
Source: https://dev.to/nasrulhazim/setting-up-bayarcash-fpx-in-laravel-the-right-way-4b2n