Dengan token pembayaran yang disimpan sebelumnya, Anda dapat membuat permintaan pembayaran yang memerlukan lebih sedikit tindakan autentikasi dari pengguna.
Pada artikel ini, kita akan membahas integrasi dasar dengan API pembayaran kami untuk pembayaran menggunakan token pembayaran yang disimpan sebelumnya di bawah jenis alur PAY
pada /payment_requests
. Sebelum memulai, pastikan Anda telah menyelesaikan pengaturan environment integrasi Anda.
Alur integrasi
Cara integrasi
Buat halaman checkout
Di aplikasi Anda, siapkan alur checkout untuk memfasilitasi langkah-langkah pembayaran yang akan dilalui pengguna akhir. Untuk langkah pertama, buat halaman checkout tempat channel pembayaran ditampilkan. Karena Anda memiliki token pembayaran yang ada, disarankan untuk menyorotinya kepada pengguna akhir atau bahkan menampilkan informasi seperti saldo (tersedia untuk channel pembayaran tertentu).
Kumpulkan data yang diperlukan untuk channel pembayaran yang dipilih
Setelah pengguna akhir memilih channel, kumpulkan data yang diperlukan untuk memulai pembayaran dengan penyedia metode pembayaran. Lihat Routing channel pembayaran untuk daftar lengkap informasi yang diperlukan.Buat permintaan pembayaran
Buat API request body untukPAY
dengan token dan dengan informasi yang diperlukan oleh channel pembayaran Anda. Dalam alur pembayaran ini, Anda tidak perlu meneruskanchannel_code
ataucustomer_id
karena sudah disimpan dalam token.Request - POST /payment_requests { "reference_id": "90392f42-d98a-49ef-a7f3-abcezas123", "payment_token_id": "pt-90392f42-d98a-49ef-a7f3-abcezas123", "type": "PAY", "country": "TH", "currency": "THB", "request_amount": 10000.01, "capture_method": "AUTOMATIC", "channel_properties": { "mid_label": "mid_label_acquirer_1", "skip_three_ds": false, "card_on_file_type": "CUSTOMER_UNSCHEDULED", "failure_return_url": "https://xendit.co/failure", "success_return_url": "https://xendit.co/success", "statement_descriptor": "Goods & Services" }, "description": "Description examples", "metadata": { "metametadata": "metametametadata" } }
Response - POST /payment_requests { "business_id": "5f27a14a9bf05c73dd040bc8", "reference_id": "90392f42-d98a-49ef-a7f3-abcezas123", "payment_token_id": "pt-90392f42-d98a-49ef-a7f3-abcezas123", "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas123", "customer_id": "cust-90392f42-d98a-49ef-a7f3-abcezas123", "type": "PAY", "country": "TH", "currency": "THB", "channel_code": "CARDS", "request_amount": 10000.01, "capture_method": "AUTOMATIC", "channel_properties": { "mid_label": "mid_label_acquirer_1", "skip_three_ds": false, "card_on_file_type": "CUSTOMER_UNSCHEDULED", "failure_return_url": "https://xendit.co/failure", "success_return_url": "https://xendit.co/success", "statement_descriptor": "Goods & Services" }, "actions": [ { "type": "REDIRECT_CUSTOMER", "value": "xendit.co/example", "descriptor": "WEB_URL" } ], "status": "REQUIRES_ACTION", "description": "Description examples", "metadata": { "metametadata": "metametametadata" }, "created": "2021-12-31T23:59:59Z", "updated": "2021-12-31T23:59:59Z" }
Fitur tambahan dapat dikonfigurasi jika channel pembayaran mengizinkannya. Misalnya, Anda akan dapat mengatur deskripsi pernyataan jika bidang properti channel menerimastatement_descriptor
parameter.Tangani tindakan yang diperlukan
Setelah berhasil membuat permintaan pembayaran dengan Xendit, Anda akan menerima objek permintaan pembayaran kami. Jika status permintaan pembayaran adalah
REQUIRES_ACTION
, Anda harus melakukan beberapa tindakan pada aplikasi klien agar pengguna akhir dapat menyelesaikan pembayaran. Jika tidak ada tindakan yang diperlukan, status pembayaran akhir akan dikembalikan secara sinkron dan webhook dengan pembaruan status pembayaran akan dikirim.Pengalihan
Tindakan "type": "REDIRECT_CUSTOMER"
Di aplikasi klien, arahkan pengguna ke nilai url dalam tindakan. Untuk memaksimalkan tingkat keberhasilan pembayaran, Anda harus menangani pengalihan berdasarkan jenis perangkat pengguna. Perhatikan bahwa untuk channel pembayaran tertentu, ada aturan pengalihan untuk tertunda atau pembatalan. Aplikasi Anda harus dirancang untuk menangani skenario tersebut.
Terima webhook event pembayaran untuk konfirmasi pembayaran
Setelah pengguna akhir menyelesaikan langkah otentikasi pembayaran mereka dan penyedia metode pembayaran memberi tahu Xendit tentang pembaruan, Xendit akan melanjutkan untuk mengirim webhook ke url webhook yang Anda konfigurasikan di halaman pengaturan dasbor Xendit Anda.{ "event": "payment.capture", "business_id": "5f27a14a9bf05c73dd040bc8", "created": "2021-12-02T14:52:21.566Z", "data": { "payment_id": "py-1402feb0-bb79-47ae-9d1e-e69394d3949c", "business_id": "5f27a14a9bf05c73dd040bc8", "reference_id": "90392f42-d98a-49ef-a7f3-abcezas123", "payment_request_id": "pr-1102feb0-bb79-47ae-9d1e-e69394d3949c", "payment_token_id": "pt-cc3938dc-c2a5-43c4-89d7-7570793348c2", "customer_id": "cust-b98d6f63-d240-44ec-9bd5-aa42954c4f48", "type": "PAY_AND_SAVE", "country": "PH", "currency": "PHP", "request_amount": 10000.01, "capture_method": "AUTOMATIC", "channel_code": "PAYMAYA", "channel_properties": { "success_return_url": "https://xendit.co/success", "failure_return_url": "https://xendit.co/failure" }, "captures": [ { "capture_timestamp": "2029-12-31T23:59:59Z", "capture_id": "cap-1502feb0-bb79-47ae-9d1e-e69394d3949c", "capture_amount": 10000.01 } ], "status": "SUCCEEDED", "payment_details": { "remark": "example remark" }, "metadata": { "metametadata": "metametametadata" }, "created": "2029-12-31T23:59:59Z", "updated": "2029-12-31T23:59:59Z" } }
Tampilkan status pembayaran kepada pengguna
Dengan status webhook, Anda seharusnya dapat menyelesaikan perjalanan pembayaran untuk pengguna akhir dengan berhasil menyelesaikan transaksi atau mengarahkan mereka kembali untuk dicoba lagi jika gagal.
Di semua sistem perpesanan real-time, ada kemungkinan webhook tidak mencapai sistem Anda. Aplikasi Anda juga harus melayani skenario di mana webhook tidak diterima saat pengguna akhir masih menunggu di layar mereka. Dalam kasus seperti itu, disarankan untuk pemberitahuan pembayaran yang tertunda diberikan kepada pengguna akhir saat Anda menunggu webhook dari Xendit.
Status Lifecycle
Perlu tindakan pengguna
Berikut adalah status lifecycle untuk permintaan pembayaran yang memerlukan tindakan pengguna:
Status | Deskripsi | Event Webhook |
---|---|---|
REQUIRES_ACTION | Permintaan pembayaran memasuki status ini secara sinkron setelah respons API jika tindakan pengguna diperlukan untuk menyelesaikan otorisasi. Tangani | - |
BERHASIL | Permintaan pembayaran beralih ke status ini saat pembayaran berhasil diselesaikan. Xendit akan mengirimkan webhook payment.capture yang berisi untuk |
|
GAGAL | Permintaan pembayaran beralih ke status ini saat pembayaran gagal. Xendit akan mengirimkan webhook payment.failure yang berisi untuk Catatan: Tidak semua channel pembayaran memberikan notifikasi untuk pembayaran yang gagal. |
|
DIBATALKAN | Anda dapat membatalkan permintaan pembayaran yang berstatus | - |
KEDALUWARSA | Permintaan pembayaran beralih ke status ini saat kedaluwarsa karena kedaluwarsa partner pembayaran. | - |
Tidak perlu tindakan
Berikut adalah status lifecycle untuk permintaan pembayaran yang tidak memerlukan tindakan:
Status | Deskripsi | Event Webhook |
---|---|---|
BERHASIL | Permintaan pembayaran bertransisi ke status ini secara sinkron saat pembayaran segera berhasil. Anda masih akan menerima webhook payment.capture yang berisi detail pembayaran. |
|
GAGAL | Permintaan pembayaran bertransisi ke status ini secara sinkron saat pembayaran segera gagal. Anda masih akan menerima webhook payment.failure. Catatan: Tidak semua channel pembayaran memberikan notifikasi untuk pembayaran yang gagal. |
|
TERTUNDA | Permintaan pembayaran memasuki status ini secara sinkron setelah respons API jika mitra pembayaran belum merespons dengan hasil pembayaran. Tunggu hingga webhook pembayaran tiba di URL webhook yang dikonfigurasi. | - |