Cara Betul Menetapkan BayarCash dalam Laravel

Jika anda membina SaaS untuk pasaran Malaysia, anda akhirnya akan memerlukan FPX. BayarCash adalah pilihan yang biasa digunakan.

SDK bukanlah masalahnya. Masalahnya adalah seni bina (architecture) anda. Jika anda memanggil SDK daripada pengawal (controller) atau menulis kod status secara keras (hardcode) dalam paparan (view) anda, anda akan menghadapi masalah dalam production.

Saya telah melaksanakan BayarCash dalam tiga aplikasi Laravel yang berbeza. Berikut adalah corak yang berkesan setiap kali.

Istilah Utama Untuk Dikuasai

  • Portal: Konfigurasi daftar keluar (checkout) pedagang anda. Gunakan portal_key.
  • API Token: Ini mengesahkan panggilan keluar anda.
  • Secret Key: Ini menandatangani payload anda dan mengesahkan webhook. Simpan ini dengan selamat.
  • Payment Intent: Anda menghantar caj, menerima URL, dan mengalihkan (redirect) pengguna.
  • Channel: Sentiasa gunakan pemalar (constants) SDK dan bukannya nombor mentah.

Strukturkan Kod Anda dengan Baik

Kod domain anda tidak sepatutnya melihat payload BayarCash yang mentah. Anda memerlukan tiga lapisan:

  • Pembungkus klien yang nipis (thin client wrapper): Ini mengendalikan konfigurasi dan menyediakan kaedah bertipe (typed methods).
  • Gerbang (gateway): Ini melaksanakan antara muka (interface) dan menggunakan bahasa domain anda.
  • Kilang (factory): Ini memilih gerbang yang aktif supaya anda boleh menukar BayarCash kepada Stripe dengan mudah.

Mengikat (Binding) Gerbang Palsu

Jika anda tidak menyediakan token API, ikat pembekal Palsu (Fake provider) dalam bekas perkhidmatan (service container) anda. Ini membolehkan ujian anda berjalan tanpa rangkaian dan membolehkan binaan tempatan (local builds) anda berjalan tanpa pengebilan aktif.

Amalan Terbaik Webhook

Webhook adalah sumber kebenaran (source of truth) anda. Ikuti peraturan ini untuk mengelakkan kekacauan semasa production:

  • Pengecualian CSRF: Laluan (route) webhook anda mesti melepasi perlindungan CSRF.
  • Sahkan Tandatangan: Sentiasa sahkan tandatangan sebelum melakukan perkara lain.
  • Peraturan 200: Sebaik sahaja anda mengesahkan tandatangan, pulangkan respons 2xx.
  • Elakkan Percubaan Semula (Retries): Jika anda memulangkan ralat 500, BayarCash akan mencuba semula webhook anda sebanyak 40 kali. Ini boleh menyebabkan pelayan anda tergendala. Log ralat, tetapi tetap pulangkan 200.
  • Idempotensi: Pastikan logik anda boleh mengendalikan webhook yang sama sebanyak dua kali tanpa mencipta pesanan pendua.

Senarai Semak untuk Kejayaan

• Gunakan order_number sebagai kunci korelasi. Pastikan ia di bawah 30 aksara. • Simpan rekod tempatan yang tertangguh (pending) sebelum anda mengalihkan pengguna. • Gunakan panggilan balik (callback) pelayan-ke-pelayan sebagai autoriti utama anda. • Gunakan URL pulangan sebagai jaring keselamatan untuk penyelarasan (reconciliation). • Petakan kod status integer kepada Enum anda sendiri dengan segera.

Integrasi pembayaran melibatkan wang sebenar. Uji pengesahan tandatangan dan idempotensi anda lebih daripada perkara lain.

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