Langkah integrasi yang selamat
API setiap gateway (cara sistem anda bercakap dengan gateway) tak sama. Tapi langkah selamatnya tetap sama. Ikut susunan ini, dan orang tak boleh palsukan bayaran.
┌────────────────────────────────────────────────────┐
│ PELANGGAN │
│ Klik "Bayar" di laman anda │
└────────────────────────────────────────────────────┘
│
│ cipta pesanan
▼
┌────────────────────────────────────────────────────┐
│ BACKEND ANDA │
│ Simpan pesanan berstatus menunggu (rujukan unik) │
└────────────────────────────────────────────────────┘
│
│ minta checkout
▼
┌────────────────────────────────────────────────────┐
│ GATEWAY │
│ Beri URL halaman bayaran gateway │
└────────────────────────────────────────────────────┘
│
│ hantar ke halaman bayaran
▼
┌────────────────────────────────────────────────────┐
│ PELANGGAN BAYAR │
│ FPX / kad / e-wallet / DuitNow QR │
└────────────────────────────────────────────────────┘
│
│ bank luluskan
▼
┌────────────────────────────────────────────────────┐
│ GATEWAY │
│ Hantar webhook yang ada signature ke backend │
└────────────────────────────────────────────────────┘
│
│ webhook
▼
╔════════════════════════════════════════════════════╗
║ BACKEND ANDA (pintu semakan) ║
║ 1. semak signature ║
║ 2. tanya semula status sebenar dari gateway ║
║ 3. padankan rujukan + jumlah + status ║
║ 4. tanda dibayar sekali sahaja ║
╚════════════════════════════════════════════════════╝
│
│ disahkan
▼
┌────────────────────────────────────────────────────┐
│ BUKA AKSES │
│ Tunjuk bayaran berjaya kepada pelanggan │
└────────────────────────────────────────────────────┘Langkah demi langkah
- 1
Cipta rekod bayaran "menunggu" dalam sistem anda
Sebelum hantar pelanggan ke halaman bayaran, simpan dulu rekod pesanan dalam sistem anda. Letak status menunggu dan satu nombor rujukan unik. Rekod inilah yang anda sahkan nanti. Jangan bergantung pada rekod gateway sahaja.
- 2
Hantar pelanggan ke halaman checkout (bayaran) gateway
Hantar pelanggan ke halaman checkout atau payment link gateway, bersama nombor rujukan dan jumlah bayaran. Biar gateway yang tunjuk pilihan kad/FPX/e-wallet. Jadi anda tak perlu simpan maklumat sensitif pelanggan langsung.
- 3
Semak signature webhook
Bila gateway hantar mesej ke backend anda, semak signature/checksum dulu sebelum baca apa-apa. Signature ialah kod rahsia yang buktikan mesej itu betul-betul dari gateway (biasanya HMAC dengan key rahsia anda). Callback yang tak lepas semakan tak boleh dipercayai. Tolak terus.
- 4
Tanya semula status dari gateway
Jangan terus percaya status dalam mesej webhook. Tanya gateway sendiri melalui API mereka untuk dapatkan status bayaran sebenar bagi nombor rujukan itu.
- 5
Padankan gateway + rujukan + jumlah + mata wang + status
Pastikan setiap maklumat bayaran sama dengan rekod menunggu anda. Kalau ada yang tak sama (jumlah salah, mata wang salah, rujukan tak dikenali), jangan hantar barang.
- 6
Tanda dibayar, sekali sahaja
Tukar rekod kepada dibayar dan buka akses. Gateway memang selalu hantar mesej yang sama lebih sekali. Kalau nombor rujukan itu dah ditanda dibayar, abaikan mesej kedua. Maksudnya, barang tak dihantar dua kali dan jualan tak dikira dua kali.
Dua peraturan paling penting
- Jangan buka akses berbayar hanya sebab pelanggan balik ke laman anda. Apa yang berlaku di browser boleh diulang atau dipalsukan. Buka akses hanya selepas webhook disemak dan status ditanya semula kepada gateway.
- Simpan rahsia di server. Key rahsia dan semakan signature mesti ada di backend (server) anda sahaja. Jangan letak dalam kod yang berjalan di browser pelanggan atau dalam repo kod projek.
Ujian yang perlu ditulis
- • Signature tak sah → ditolak, tiada barang dihantar.
- • Webhook yang sama sampai dua kali → diproses sekali sahaja.
- • Jumlah atau mata wang salah → tidak ditanda dibayar.