Safe Acceptance

Bagian ini akan menunjukan pada Anda tentang bagaimana membuat charge kartu kredit menggunakan API Safe Acceptance.

Menggunakan Token

Jika alur pembayaran Anda menggunakan API tokenisasi, Anda dapat mengikuti langkah-langkah di bawah ini:

1. Kirimkan detil informasi kartu dari sisi front-end Anda (client) ke API tokenisasi melalui xendit.js atau Xendit SDK.
2. Anda dapat memilih untuk melakukan 3DS atau tidak menggunakan parameter should_authenticate pada body request tokenisasi Anda.
3. Xendit akan memberikan token_id pada body respon tokenisasi (dan juga body response otentikasi apabila Anda melakukan 3DS).
4. Gunakan nilai pada token_id yang sebelumnya didapat pada saat Anda mengirimkan request Safe Acceptance termasuk pembuatan tanda tangan dan validasi. Sebagai catatan, jika Anda telah melakukan 3DS pada bagian tokenisasi, Anda tidak perlu melakukan 3DS lagi pada saat mengirimkan request Safe Acceptance.
5. Anda akan mendapatkan hasil berupa pembayaran berhasil atau pembayaran gagal melalui webhook dari Safe Acceptance API pada parameter return_url yang Anda set pada saat melakukan request sebelumnya.

Menggunakan Nomor Kartu dengan Lengkap (PAN)

Jika Anda lebih suka untuk melakukan charge pada kartu secara langsung dari front-end Anda, Anda dapat mengikuti langkah berikut:

1. Kirimkan detil informasi kartu dari sisi front-end Anda (client) ke API Safe Acceptance secara langsung termasuk tanda tangan dan validasi.
2. Pada body request Anda, Anda dapat memasukkan nomor kartu secara lengkap pada parameter card_number (Anda harus memasukkan sebanyak mungkin detil informasi kartu). Pastikan informasi nomor kartu tidak dikirim secara langsung dari backend Anda karena akan melanggar standar keamanan PCI-DSS jika Anda belum tersertifikasi.
3. Jika Anda ingin melakukan 3DS pada transaksi, Anda dapat mengatur nilai pada parameter should_authenticate menjadi true pada body request Safe Acceptance Anda.
4. Jika 3DS sudah dilakukan, maka Xendit akan mengirimkan respon yang berisikan URL yang diperlukan untuk proses 3DS seperti halaman verifikasi yang disediakan oleh Visa dan Mastercard. Bagian ini harus ditangani oleh front-end Anda dan harus terlihat oleh pemilik kartu untuk proses 3DS.
5. Ketika proses 3DS selesai, Xendit akan memproses pembayaran.
6. Anda akan mendapatkan hasil berupa pembayaran berhasil atau pembayaran gagal melalui webhook dari Safe Acceptance API pada parameter return_url yang Anda set pada saat melakukan request sebelumnya.

Membuat Tanda Tangan

Menggunakan API Safe Acceptance, komunikasi antara sisi Anda dengan Xendit akan dilakukan secara langsung dari front-end Anda. Mekanisme komunikasi ini dianggap kurang aman dibanding dengan komunikasi back end server-to-server karena pihak lain dapat mengintervensi dan mengubah pesan yang dikirim atau diterima pada saat transmisi pesan.

API ini menggunakan tanda tangan sebagai validator untuk request dan respon. Tanda tangan didapatkan pada request dan respon dengan melakukan hash pada shared secret key yang hanya diketahui oleh Anda dan Xendit.

Jika Anda melakukan verifikasi pada tanda tangan yang ada pada respon dari Xendit dan tidak sesuai dengan yang Anda miliki, maka kemungkinan hal ini terjadi karena terdapat fraud atau jalur komunikasi antara Xendit dan Anda telah disusupi oleh pihak luar. Pada kejadian seperti, Anda harus menolak transaksi tersebut demi keamanan.

Silakan lihat alur pada Safe Acceptance API di bawah ini yang sudah termasuk proses pembuatan tanda tangan dan validasi.

1. Pelanggan Anda mengklik tombol bayar pada halaman pembayaran Anda yang secara langsung akan mengirimkan request ke API Xendit.
2. Backend Anda membuat tanda tangan dengan menggunakan informasi yang ada pada detil order (detil pesanan dari pelanggan). Tanda tangan yang Anda buat ini akan diberikan ke Xendit untuk melakukan verifikasi apakah request yang akan dikirimkan untuk transaksi ini adalah benar dilakukan oleh Anda (bukan pihak lain).
3. Pelanggan Anda akan diarahkan ke halaman pembayaran dengan informasi mengenai pembayaran secara lengkap.
4. Pelanggan Anda mengklik tombol bayar dan Safe Acceptance API akan dipanggil menggunakan request POST dari sisi Anda.
5. Xendit menerima request pembayaran dan akan mengarahkan pelanggan Anda ke halaman otentikasi apabila alur pembayaran Anda mengharuskan proses otentikasi.
6. Pelanggan Anda menyelesaikan proses otentikasi dan konfirmasi akan dikirimkan ke sisi Xendit.
7. Xendit mengkonfirmasi pembayaran tersebut, mengirimkan respon pembayaran dan mengarahkan pelanggan Anda kembali ke halaman pembayaran Anda. Tanda tangan dari Xendit pada bagian ini menjadi tanda bahwa respon yang diberikan adalah dari Xendit dan bukan dari pihak lain.
8. Setelah proses redirection/pengalihan dari Xendit, browser pelanggan Anda akan memuat halaman pembayaran Anda dan mengirimkan respon pembayaran dan tanda tangan dari Xendit ke backend Anda.
9. Anda membuat tanda tangan baru menggunakan respon dari pembayaran dan melakukan verifikasi untuk memastikan tanda tangan sama dengan yang dikirimkan oleh Xendit.
10. Halaman penyelesaian pembayaran akan dimuat untuk memberikan informasi ke pelanggan Anda bahwa pembayaran telah berhasil dilakukan.

Skenario Pengujian

Gunakan halaman demo berikut ini untuk melakukan pengujian menggunakan Safe Acceptance API.

Skenario Positif

Skenario	Kriteria	Hasil
VISA MC JCB dengan nomor kartu lengkap	Gunakan nomor kartu lengkap dengan channel_code kosong - Visa: 4000 0000 0000 0002 - MC: 5555 5555 5555 4444 - JCB: 3566 1111 1111 1113 Exp date (Semua kartu): 05/25 CVN (Semua kartu): 123	Pelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan status CAPTURED.
VISA MC JCB dengan multi-use token	Gunakan token_id denganchannel_code kosong	Pelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan status CAPTURED.
GPN	Nomor token_id dan nomor kartu dengan channel_code = GPN	Pelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan status CAPTURED.
BCA	Nomor token_id dan nomor kartu dengan channel_code = BCA BCA:** 1889800000000171 Exp. date: 03/21 CVN: 101 OTP: 123456	Pelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan status CAPTURED.

Skenario Negatif

Skenario	Kriteria	Hasil
Request duplikat dari merchant	Transaksi dikirim dengan id referensi yang sama	Pelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan alasan kegagalan DUPLICATE_EXTERNAL_ID_ERROR
Tanggapan callback dengan tanda tangan tidak valid	Diberikan request dengan tanda tangan tidak valid	Pelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan alasan kegagalan SIGNATURE_VALIDATION_ERROR
Request replay dari pihak jahat	Diberikan request yang berhasil jika transaksi lain diputar ulang oleh pihak jahat dengan stempel waktu request yang berbeda	Pelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan alasan kegagalan SIGNATURE_VALIDATION_ERROR
Penolakan kartu	Diberikan request dengan tanda tangan yang sah dan biaya dengan 5001 IDR	Pelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan alasan kegagalan CARD_DECLINED