Sebelum memulai, pastikan Anda telah menyelesaikan hal berikut:
Create an API Key di Dasbor Xendit Anda. Anda memerlukan Kunci API untuk melakukan panggilan API.
Siapkan URL webhook Anda. Konfigurasikan ini untuk menerima notifikasi real-time tentang perubahan status payout.
Lihat Cakupan Payout untuk informasi khusus channel. Anda perlu tahu informasi apa yang perlu dikumpulkan untuk mulai mengirim Payout.
Buat Payout
Hubungi Create Payout API
dengan penerima yang diperlukan dan informasi transaksi untuk membuat Payout.
Contoh request
curl https://api.xendit.co/v2/payouts -X POST \
-u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==: \
--header 'Idempotency-key: some-unique-ref-for-request'
--data-raw '{
"reference_id": "sample-successful-create-php-payout",
"channel_code": "PH_GCASH",
"channel_properties": {
"account_number": "0000000000",
"account_holder_name": "Test"
},
"amount": 1.11,
"description": "Sample Successful Create PHP Payout",
"currency": "PHP",
"receipt_notification": {
"email_to": [
"somebody@xendit.co",
"somebody@example.co"
],
"email_cc": [
"somebody@example.co",
"somebody@example.co"
],
"email_bcc": [
"somebody@example.co",
"somebody@example.co"
]
},
"metadata": {
"outlet_no": 24
}
}'
Contoh response
Jika berhasil dibuat, kami akan selalu mengembalikan objek payout dengan ACCEPTED
status.
{
"id": "disb-1475459775872",
"amount": 1.11,
"channel_code": "PH_GCASH",
"currency": "PHP",
"description": "Sample Successful Create PHP Payout",
"reference_id": "sample-successful-create-php-payout",
"status": "ACCEPTED",
"created": "2022-01-05T05:37:48.108Z",
"updated": "2022-01-05T05:37:48.108Z",
"estimated_arrival_time": "2022-01-05T05:52:48.106Z",
"business_id": "6018306aa16ad90cb3c43ba7",
"channel_properties": {
"account_number": "0000000000",
"account_holder_name": "Test"
},
"receipt_notification": {
"email_to": [
"somebody@example.co",
"somebody@example.co"
],
"email_cc": [
"somebody@example.co",
"somebody@example.co"
],
"email_bcc": [
"somebody@example.co",
"somebody@example.co"
]
},
"metadata": {
"outlet_no": 24
}
}
Menghindari pembuatan Payout duplikat
Kami menggunakan idempotency-key
untuk mencapai idempotensi dan menghindari pembuatan transaksi Payout duplikat. Jika request pertama gagal karena error atau batas waktu, Anda dapat mencoba lagi dengan aman dengan menggunakan nilai yang sama idempotency-key
di header request percobaan lagi berikutnya. Ini akan membantu kami mengidentifikasi request percobaan ulang berikutnya sebagai upaya coba lagi dan tidak akan membuat transaksi Payout duplikat.
Kirim bukti Payout
Kami menyediakan tanda terima email otomatis yang dapat Anda kirimkan kepada Anda dan penerima Anda sebagai pemberitahuan tentang bukti Payout. Untuk melakukan ini, pastikan untuk mengisi email_to
kolom , email_cc
, dan email_bcc
(dengan maksimum 3 penerima per bidang) di bawah receipt_notification
parameter.
Kami menampilkan logo dan detail bisnis Anda di setiap tanda terima. Pastikan untuk menguji tanda terima dengan menyertakan alamat email Anda dalam request Payout. Anda kemudian dapat melihat seperti apa tanda terima email di kotak masuk Anda.
Pastikan penerima mengidentifikasi Payout Anda
Kami membayar dana atas nama Anda dari rekening bank kami. Untuk membantu penerima mengidentifikasi dana dari Anda, sertakan nama bisnis atau ID apa pun dalam description
parameter - jika channel penerima mendukung kolom ini, penerima akan melihatnya di laporan mereka. Dalam kebanyakan kasus, hanya sejumlah karakter yang didukung, jadi jaga agar pengidentifikasi Anda tetap singkat dan ringkas.
Baca Payout Coverage untuk detail khusus channel lainnya.
Mengambil Payout
Hubungi Get Payout by ID API
atau Get Payout by Reference ID API
untuk mengambil detail Payout. Ini biasanya berguna untuk mendapatkan status Payout Anda. Selain itu, kami menyarankan Anda untuk berlangganan event webhook kami untuk pembaruan status Payout Anda.
Untuk informasi selengkapnya, lihat Set up webhooks.
Mengambil Payout berdasarkan ID-nya
Panggil Get Payout by ID API
untuk mengambil payout berdasarkan ID-nya. Selalu kembalikan satu payout.
Contoh request
curl https://api.xendit.co/v2/payouts/disb-b57fff2d-9699-470b-9978-ac509c5b266c -X GET \
-u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:
Contoh response
{
"id": "disb-1475459775872",
"amount": 100,
"channel_code": "ID_BCA",
"currency": "IDR",
"description": "Sample Failed Create Payout",
"estimated_arrival_time": "2022-01-05T06:09:23.667Z",
"failure_code": "TEMPORARY_TRANSFER_ERROR",
"reference_id": "sample-failed-create-payout",
"status": "FAILED",
"created": "2022-01-05T05:54:23.670Z",
"updated": "2022-01-05T05:54:35.680Z",
"business_id": "5785e6334d7b410667d355c4",
"channel_properties": {
"account_number": "123456",
"account_holder_name": "Test"
}
}
Mengambil Payout berdasarkan ID Referensinya
Panggil Get Payout by Reference ID API
untuk mengambil Payout berdasarkan ID referensinya. Dapat mengembalikan beberapa Payout dalam array.
Memanggil API ini akan mengambil semua payout dengan ID referensi yang cocok. Menampilkan array Objek Payout yang cocok jika reference_id
valid disediakan. Mengembalikan array kosong jika tidak ada Payout yang sesuai dengan .reference_id
Contoh request
curl https://api.xendit.co/v2/payouts?reference_id=lotto-1482928194&limit=10&after_id=disb-cc7cd9c0-1971-4414-9b54-be545948a33d&before_id=disb-69d8e2ba-20f9-41af-bd04-e299237fd7ec -X GET \
-u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:
Contoh respons
Jika lebih dari satu payout memiliki reference_id yang sama dengan yang disediakan, akan mengembalikan berbagai payout.
[
{
"id": "disb-1475459775872",
"amount": 100,
"channel_code": "ID_BCA",
"currency": "IDR",
"description": "Sample Failed Create Payout",
"estimated_arrival_time": "2022-01-05T06:09:23.667Z",
"failure_code": "TEMPORARY_TRANSFER_ERROR",
"reference_id": "sample-failed-create-payout",
"status": "FAILED",
"created": "2022-01-05T05:54:23.670Z",
"updated": "2022-01-05T05:54:35.680Z",
"business_id": "5785e6334d7b410667d355c4",
"channel_properties": {
"account_number": "123456",
"account_holder_name": "Test"
}
},
{
"id": "disb-567845975142",
"amount": 200,
"channel_code": "ID_BCA",
"currency": "IDR",
"description": "Sample Failed Create Payout2",
"estimated_arrival_time": "2022-01-05T06:14:23.667Z",
"failure_code": "TEMPORARY_TRANSFER_ERROR",
"reference_id": "sample-failed-create-payout2",
"status": "FAILED",
"created": "2022-01-05T05:58:23.670Z",
"updated": "2022-01-05T05:58:35.680Z",
"business_id": "5785e6334d7b410667d355c4",
"channel_properties": {
"account_number": "123456",
"account_holder_name": "Test"
}
}
]
Batalkan Payout
Panggilan Cancel Payout API
untuk membatalkan transaksi yang belum diproses oleh mitra Xendit.
Payout hanya dapat dibatalkan jika statusnya adalah ACCEPTED
. Disarankan untuk merujuk ke untuk Get Payout API
mengetahui apakah Payout masih dapat dibatalkan atau tidak. Setelah request pembatalan, kami akan mengembalikan response dengan CANCELLED
status. Dana Anda diharapkan dikembalikan ke saldo yang tersedia dalam waktu 5 menit.
Jika pembatalan gagal, kami akan mengirimkan kembali alasan kegagalan yang sesuai di mana dana dan biaya akan tetap ada di saldo tertunda Anda hingga mencapai status akhir dari mitra (SUCCEEDED
atau FAILED
). Alasan umum mungkin karena request Payout yang tidak valid yang tidak ada, atau Payout sudah diproses oleh mitra.
Contoh request
curl https://api.xendit.co/v2/payouts/disb-b57fff2d-9699-470b-9978-ac509c5b266c/cancel -X POST \
-u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:
Contoh respons
{
"id": "disb-1475459775872",
"amount": 250000,
"channel_code": "PH_CITI",
"currency": "PHP",
"description": "rewards",
"reference_id": "test-rewards-001",
"status": "CANCELLED",
"created": "2022-01-16T12:11:22.233Z",
"updated": "2022-01-16T12:21:31.373Z",
"estimated_arrival_time": "2022-01-16T12:26:22.155Z",
"business_id": "5785e6334d7b410667d355c4",
"channel_properties": {
"payout_code": "002912362381009082189137",
"recipient_given_names": "Michael",
"recipient_surname": "Chen",
"expires_at": "2022-01-23T12:11:22.156Z"
}
}
Penanganan Kesalahan
Kesalahan Umum dalam Payout
Di bawah ini adalah daftar kesalahan umum yang mungkin Anda temui saat menggunakan API Payout. Untuk pemahaman sederhana, kami telah membaginya menjadi 2 kategori:
Kesalahan dalam membuat Payout
Kesalahan dalam mengeksekusi Payout
Kesalahan Dalam Membuat Payout
Semua kemungkinan error saat membuat payout melalui endpoint API kami tercantum di halaman ini.
Untuk kesalahan umumnya, respons yang Anda terima akan berisi:
error_code
: Kode semantik yang menentukan kesalahan yang ditemui;message
: Pernyataan singkat yang menjelaskan kode.
Contoh:
{
"error_code": "DUPLICATE_ERROR",
"message": "A payout with this idempotency key already exists. If you meant to execute a different request, please use another idempotency key."
}
Jika Anda menerima error dalam respons API kami, ini berarti ada masalah saat membuat payout karena input yang tidak valid atau masalah dengan server. Untuk instruksi penanganan terperinci dari setiap kesalahan, silakan lihat tabel di bawah ini:
Kode kesalahan | Penjelasan |
---|---|
| Input tertentu tidak memenuhi persyaratan validasi API kami. |
| Kunci idempotensi telah digunakan sebelumnya. Gunakan kunci idempotensi unik dan coba lagi. |
| Setiap channel memiliki jumlah transaksi minimum dan maksimum. Kami akan mengembalikan respons kesalahan jika jumlah transfer yang diminta tidak sesuai dengan batas yang ditentukan. Lihat Cakupan Payout. |
| Setiap channel memiliki dukungan peningkatan yang berbeda. Kami akan mengembalikan respons kesalahan jika jumlah transfer yang diminta tidak sesuai dengan dukungan kenaikan yang ditentukan. |
Kesalahan Dalam Menjalankan Payout
Setelah status payout adalah REQUESTED
, status payout mungkin gagal dalam pemrosesan partner payout kami atau ditolak oleh bank penerima, di mana statusnya akan beralih ke FAILED
. Berlangganan payout.failed
event webhook untuk menerima pemberitahuan real-time tentang setiap kegagalan transfer dan alasannya.
Penting bagi Anda untuk memahami setiap kode kegagalan secara rinci untuk memutuskan tindakan yang tepat untuk diambil. Di bawah ini adalah daftar lengkap kemungkinan kode kegagalan yang mungkin Anda terima, apa artinya, dan apa tindakan yang kami sarankan yang sesuai:
Pesan Kesalahan | Deskripsi | Haruskah Anda mencoba lagi? |
---|---|---|
| Klien memiliki saldo yang tidak mencukupi untuk jumlah Payout | Ya, coba kembali Payout setelah memastikan bahwa Anda memiliki saldo yang cukup di akun Anda |
| Akun penerima tidak ada/tidak valid | Anda tidak mungkin berhasil jika mencoba kembali request payout. Harap konfirmasi dengan penerima apakah akun mereka benar |
| Penerima tidak dapat menerima dana karena jumlah Payout melebihi kemampuan penerima untuk menerima | Anda tidak mungkin berhasil jika mencoba kembali request payout. Harap konfirmasi dengan penerima apakah akun mereka dapat menerima Payout |
| Payout gagal karena error dari channel tujuan. Hal ini biasanya karena masalah jaringan yang terkait dengan bank tujuan atau penerbitan pengkreditan dana ke rekening bank tujuan | Ya, coba kembali Payout setelah memvalidasi bahwa nomor rekening bank tujuan aktif dan dapat menerima dana dalam mata uang yang Anda pilih |
| Jaringan channel mengalami kesalahan sementara | Ya, coba kembali Payout dalam 1-3 jam |
| Kami mengalami error fatal saat memproses Payout ini. Biasanya, ini berarti bahwa kolom API tertentu dalam request Anda tidak valid | Tidak mungkin request pencairan yang sama akan berhasil jika Anda mencoba lagi |
Catatan: Kita dapat menambahkan kode kegagalan baru ke daftar di atas dan sistem Anda harus dapat menangani event tersebut meskipun kode kegagalan tidak dikenali.
Event Payout
Pelajari lebih lanjut di bawah ini untuk berbagai event webhook yang dapat Anda langganan. Untuk informasi selengkapnya tentang berbagai status payout, lihat Payout Status Lifecycle.
Event Webhook | Status Payout |
---|---|
|
|
|
|
|
|