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_tokolom , 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
`API_VALIDATION_ERROR` `CHANNEL_CODE_NOT_SUPPORTED` `RECIPIENT_ACCOUNT_NUMBER_ERROR`	Input tertentu tidak memenuhi persyaratan validasi API kami.
`DUPLICATE_ERROR`	Kunci idempotensi telah digunakan sebelumnya. Gunakan kunci idempotensi unik dan coba lagi.
`MINIMUM_TRANSFER_LIMIT_ERROR` `MAXIMUM_TRANSFER_LIMIT_ERROR`	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.
`AMOUNT_INCREMENT_NOT_SUPPORTED`	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?
`INSUFFICIENT_BALANCE`	Klien memiliki saldo yang tidak mencukupi untuk jumlah Payout	Ya, coba kembali Payout setelah memastikan bahwa Anda memiliki saldo yang cukup di akun Anda
`INVALID_DESTINATION`	Akun penerima tidak ada/tidak valid	Anda tidak mungkin berhasil jika mencoba kembali request payout. Harap konfirmasi dengan penerima apakah akun mereka benar
`DESTINATION_MAXIMUM_LIMIT`	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
`REJECTED_BY_CHANNEL`	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
`TEMPORARY_TRANSFER_ERROR`	Jaringan channel mengalami kesalahan sementara	Ya, coba kembali Payout dalam 1-3 jam
`TRANSFER_ERROR`	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
`payout.succeeded`	`SUCCEEDED`
`payout.failed`	`FAILED`
`payout.reversed`	`REVERSED`