Cách thiết lập BayarCash trong Laravel một cách chuẩn nhất

Nếu bạn xây dựng SaaS cho thị trường Malaysia, cuối cùng bạn sẽ cần đến FPX. BayarCash là một lựa chọn phổ biến.

SDK không phải là vấn đề. Vấn đề nằm ở kiến trúc của bạn. Nếu bạn gọi SDK từ một controller hoặc viết cứng (hardcode) các mã trạng thái trong view, bạn sẽ gặp rắc rối khi triển khai thực tế (production).

Tôi đã triển khai BayarCash trên ba ứng dụng Laravel khác nhau. Đây là mô hình (pattern) luôn hoạt động hiệu quả.

Các thuật ngữ chính cần nắm vững

  • Portal: Cấu hình thanh toán của người bán. Sử dụng portal_key.
  • API Token: Dùng để xác thực các cuộc gọi đi của bạn.
  • Secret Key: Dùng để ký các payload và xác thực webhooks. Hãy giữ nó an toàn.
  • Payment Intent: Bạn gửi một yêu cầu thanh toán, nhận về một URL và chuyển hướng người dùng.
  • Channel: Luôn sử dụng các hằng số (constants) của SDK thay vì các con số thô.

Cấu trúc mã nguồn tốt

Mã nguồn domain của bạn không bao giờ nên tiếp xúc trực tiếp với payload thô của BayarCash. Bạn cần ba lớp:

  • Một client wrapper mỏng: Xử lý cấu hình và cung cấp các phương thức có kiểu dữ liệu (typed methods).
  • Một gateway: Triển khai một interface và sử dụng ngôn ngữ domain của bạn.
  • Một factory: Chọn gateway đang hoạt động để bạn có thể dễ dàng thay thế BayarCash bằng Stripe.

Liên kết một Fake Gateway

Nếu bạn không cung cấp API token, hãy liên kết một Fake provider trong service container. Điều này cho phép các bài kiểm tra (tests) chạy mà không cần mạng và giúp các bản build cục bộ chạy mà không cần thanh toán thực tế.

Các thực hành tốt nhất cho Webhook

Webhook là nguồn dữ liệu chuẩn (source of truth) của bạn. Hãy tuân thủ các quy tắc sau để tránh các sự cố dồn dập khi chạy production:

  • Miễn trừ CSRF: Route webhook của bạn phải bỏ qua sự bảo vệ CSRF.
  • Xác thực chữ ký: Luôn luôn xác thực chữ ký trước khi thực hiện bất kỳ thao tác nào khác.
  • Quy tắc 200: Ngay sau khi xác thực chữ ký thành công, hãy trả về phản hồi 2xx.
  • Tránh việc thử lại (retries): Nếu bạn trả về lỗi 500, BayarCash sẽ thử lại webhook của bạn tới 40 lần. Điều này có thể làm sập máy chủ của bạn. Hãy ghi log lỗi, nhưng vẫn trả về mã 200.
  • Tính lũy đẳng (Idempotency): Đảm bảo logic của bạn có thể xử lý cùng một webhook hai lần mà không tạo ra các đơn hàng trùng lặp.

Danh sách kiểm tra để thành công

• Sử dụng order_number làm khóa tương quan (correlation key). Giữ nó dưới 30 ký tự. • Lưu một bản ghi chờ (pending) tại local trước khi chuyển hướng người dùng. • Sử dụng server-to-server callback làm nguồn xác thực chính. • Sử dụng return URL như một lưới an toàn để đối soát (reconciliation). • Ánh xạ các mã trạng thái kiểu số nguyên sang các Enum của riêng bạn ngay lập tức.

Tích hợp thanh toán liên quan đến tiền thật. Hãy kiểm tra việc xác thực chữ ký và tính lũy đẳng nhiều hơn bất cứ thứ gì khác.

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