Bahasa Indonesia
API ReferenceLogin

Creating Charges - Safe Acceptance

Last updated 06/02/2021

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.

Safe Acceptance API

  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

SkenarioKriteriaHasil
VISA MC JCB dengan nomor kartu lengkapGunakan 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 tokenGunakan token_id denganchannel_code kosongPelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan status CAPTURED.
GPNNomor token_id dan nomor kartu dengan channel_code = GPNPelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan status CAPTURED.
BCANomor 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

SkenarioKriteriaHasil
Request duplikat dari merchantTransaksi dikirim dengan id referensi yang samaPelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan alasan kegagalan DUPLICATE_EXTERNAL_ID_ERROR
Tanggapan callback dengan tanda tangan tidak validDiberikan request dengan tanda tangan tidak validPelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan alasan kegagalan SIGNATURE_VALIDATION_ERROR
Request replay dari pihak jahatDiberikan request yang berhasil jika transaksi lain diputar ulang oleh pihak jahat dengan stempel waktu request yang berbedaPelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan alasan kegagalan SIGNATURE_VALIDATION_ERROR
Penolakan kartuDiberikan request dengan tanda tangan yang sah dan biaya dengan 5001 IDRPelanggan akan diarahkan ke halaman lengkap pembayaran merchant. Kami akan mengirimkan respon dengan alasan kegagalan CARD_DECLINED