Правильная настройка BayarCash в Laravel

Если вы создаете SaaS для малайзийского рынка, вам рано или поздно понадобится FPX. BayarCash — популярный выбор.

Проблема не в SDK. Проблема в вашей архитектуре. Если вы вызываете SDK напрямую из контроллера или жестко прописываете коды статусов в представлениях (views), в продакшене вы столкнетесь с проблемами.

Я внедрял BayarCash в трех разных приложениях на Laravel. Вот паттерн, который работает каждый раз.

Ключевые термины, которые нужно освоить

  • Portal: Конфигурация оформления заказа вашего мерчанта. Используйте portal_key.
  • API Token: Аутентифицирует ваши исходящие запросы.
  • Secret Key: Подписывает ваши полезные нагрузки (payloads) и проверяет вебхуки. Храните его в безопасности.
  • Payment Intent: Вы отправляете запрос на оплату, получаете URL и перенаправляете пользователя.
  • Channel: Всегда используйте константы SDK вместо «сырых» чисел.

Правильно структурируйте код

Ваш доменный код никогда не должен видеть «сырую» полезную нагрузку BayarCash. Вам нужны три уровня:

  • Тонкая обертка клиента (client wrapper): обрабатывает конфигурацию и предоставляет типизированные методы.
  • Шлюз (gateway): реализует интерфейс и говорит на языке вашей предметной области.
  • Фабрика (factory): выбирает активный шлюз, чтобы вы могли легко заменить BayarCash на Stripe.

Привязка фиктивного шлюза

Если API-токен не предоставлен, привяжите Fake-провайдер в сервис-контейнере. Это позволит вашим тестам работать без доступа к сети, а локальным сборкам — без активных платежей.

Лучшие практики работы с вебхуками

Вебхук — это ваш первоисточник истины. Следуйте этим правилам, чтобы избежать «шторма» в продакшене:

  • Исключение из CSRF: Ваш маршрут вебхука должен обходить защиту CSRF.
  • Проверка подписей: Всегда проверяйте подпись, прежде чем выполнять какие-либо действия.
  • Правило 200: Как только вы проверили подпись, верните ответ 2xx.
  • Избегайте повторных попыток: Если вы вернете ошибку 500, BayarCash будет пытаться отправить вебхук 40 раз. Это может привести к падению вашего сервера. Логируйте ошибки, но все равно возвращайте 200.
  • Идемпотентность: Убедитесь, что ваша логика может обработать один и тот же вебхук дважды, не создавая дубликатов заказов.

Чек-лист для успеха

• Используйте order_number в качестве ключа корреляции. Ограничьте его длину 30 символами. • Сохраните локальную запись со статусом «в ожидании» (pending) перед тем, как перенаправить пользователя. • Используйте callback-уведомление (server-to-server) как основной источник данных. • Используйте return URL в качестве страховочной сетки для сверки данных. • Сразу же сопоставляйте целочисленные коды статусов со своими собственными Enum.

Интеграция платежей связана с реальными деньгами. Тестируйте проверку подписи и идемпотентность больше всего остального.

Source: https://dev.to/nasrulhazim/setting-up-bayarcash-fpx-in-laravel-the-right-way-4b2n