Welcome to Xendit’s latest documentation. For legacy content, access the previous documentation here or the previous API reference here.

Cross-Border Payouts

Prev Next

Sebelum memulai, pastikan Anda telah menyelesaikan hal berikut:

  • Buat Kunci API 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 Pembayaran untuk informasi khusus channel. Anda perlu tahu informasi apa yang perlu dikumpulkan untuk mulai mengirim pembayaran.

Buat Pengirim dan/atau Penerima

Panggilan Create Customer API untuk membuat pengirim dan/atau penerima Cross-Border Payout dengan informasi mereka.

Contoh request

curl https://api.xendit.co/customers -X POST \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==: \
   -H 'Content-Type: application/json'
   --data-raw '{
     "reference_id": "demo_1475801962607",
     "type": "INDIVIDUAL",
     "individual_detail": {
       "given_names": "John",
       "surname": "Doe"
     },
     "email": "customer@website.com",
     "mobile_number": "+628121234567890"
     }'

Contoh response

{
    "id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
    "reference_id": "demo_1475801962607",
    "type": "INDIVIDUAL",
    "individual_detail": {
        "given_names": "John",
        "surname": "Doe",
        "nationality": "ID",
        "place_of_birth": "Jakarta",
        "date_of_birth": "1980-01-01",
        "gender": "MALE",
        "employment": {
            "employer_name": "Xendit",
            "nature_of_business": "Payment Gateway",
            "role_description": "Test dummy"
        }
    },
    "business_detail": null,
    "email": "customer@website.com",
    "mobile_number": "+628121234567890",
    "phone_number": "+628121234567890",
    "hashed_phone_number": null,
    "addresses": [{
        "street_line1": "Panglima Polim IV",
        "street_line2": "Ruko Grand Panglima Polim, Blok E",
        "city": "Jakarta Selatan",
        "province_state": "DKI Jakarta",
        "postal_code": "993448",
        "country": "ID",
        "category": "HOME",
        "is_primary": true
    }],
    "identity_accounts": [{
        "type": "CREDIT_CARD",
        "company": "OCBC",
        "description": "My account",
        "country": "ID",
        "properties":{
            "token_id": "586f0ba2ab70de5d2b409e0d"
        }
    }],
    "kyc_documents": [{
        "type": "IDENTITY_CARD",
        "sub_type": "NATIONAL_ID",
        "country": "ID",
        "document_name": "KTP",
        "document_number": "12356789012456",
        "expires_at": null,
        "holder_name": "John Doe",
        "document_images": [
            "file-ec700c1c-db17-4496-b1fb-04ebe551b412"
        ]
    }],
    "description": "My first customer",
    "date_of_registration": "2020-03-30",
    "domicile_of_registration": "ID",
    "metadata": {
        "foo": "bar"
    },
    "created": "2020-03-30T06:12:47.212Z",
    "updated": "2020-03-30T06:12:47.212Z"
}

Buat Cross-Border Payout

Hubungi Create Cross Border Payout API dengan informasi pengirim dan penerima yang diperlukan untuk membuat Cross-Border Payout.

Contoh request

curl --request POST \
  --url https://api.xendit.co/remittance_payouts \
  --header 'Authorization: {{base_64_of_your_secret_api_key}}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'IDEMPOTENCY-KEY: ' \
  --data '{
  "reference_id": "49d056bd-21e5-4997-85f2-2127544c2196",
  "destination_currency": "PHP",
  "destination_amount": "35",
  "sender_customer_id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
  "recipient_customer_id": "cust-f71ffaa8-95a2-47ba-b486-cfe9e2c075d7",
  "origin_currency": "IDR",
  "origin_amount": "10000",
  "source_of_fund": "OTHER",
  "purpose_code": "OTHER",
  "relationship": "CUSTOMER",
  "description": "This is a sample Cross-border Payout transaction",
  "metadata": {}
}'

Contoh response

Jika berhasil dibuat, kami akan selalu mengembalikan objek payout dengan ACCEPTED status.

{
  "id": "rpo_cde3dcb8-37d7-4ea1-a275-8f54af81feb0",
  "created": "2024-05-01T07:15:22Z",
  "updated": "2024-05-01T07:15:22Z",
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "49d056bd-21e5-4997-85f2-2127544c2196",
  "destination_currency": "PHP",
  "destination_amount": 35,
  "sender_customer_id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
  "recipient_customer_id": "cust-f71ffaa8-95a2-47ba-b486-cfe9e2c075d7",
  "status": "ACCEPTED",
  "description": "This is a sample Cross-border Payout transaction",
  "source_of_fund": "OTHER",
  "origin_currency": "IDR",
  "origin_amount": "10000",
  "purpose_code": "OTHER",
  "relationship": "CUSTOMER",
  "failure_code": "string",
  "metadata": {}
}

Hindari membuat Pembayaran duplikat

Kami menggunakan idempotency-key untuk mencapai idempotensi dan menghindari pembuatan transaksi Cross-Border 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 Cross-Border Payout duplikat.

Pastikan penerima mengidentifikasi pembayaran 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 Cross-Border Payout

Hubungi Get Cross Border Payout by ID API untuk mengambil detail Cross-Border Payout. Ini biasanya berguna untuk mendapatkan status pembayaran Anda. Selain itu, kami menyarankan Anda untuk berlangganan event webhook kami untuk pembaruan status pembayaran Anda.

Untuk informasi selengkapnya, lihat Setting Up Webhooks.

Contoh request

curl https://api.xendit.co/remittance_payouts/rpo_cde3dcb8-37d7-4ea1-a275-8f54af81feb0 -X GET \
  -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:

Contoh response

{
  "id": "rpo_cde3dcb8-37d7-4ea1-a275-8f54af81feb0",
  "created": "2024-05-01T07:15:22Z",
  "updated": "2024-05-01T07:15:22Z",
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "49d056bd-21e5-4997-85f2-2127544c2196",
  "destination_currency": "PHP",
  "destination_amount": 35,
  "sender_customer_id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
  "recipient_customer_id": "cust-f71ffaa8-95a2-47ba-b486-cfe9e2c075d7",
  "status": "FAILED",
  "description": "This is a sample Cross-border Payout transaction",
  "source_of_fund": "OTHER",
  "origin_currency": "IDR",
  "origin_amount": "10000",
  "purpose_code": "OTHER",
  "relationship": "CUSTOMER",
  "failure_code": "INVALID_DESTINATION",
  "metadata": {}
}

Batalkan Cross-Border Payout

Panggilan Cancel Cross Border Payout API untuk membatalkan transaksi yang belum diproses oleh mitra Xendit.

Cross-Border Payout hanya dapat dibatalkan jika statusnya adalah ACCEPTED dan PENDING_COMPLIANCE_ASSESSMENT. Disarankan untuk merujuk ke untuk Get Cross Border Payout API mengetahui apakah Cross-Border 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 pembayaran yang tidak valid yang tidak ada, atau pembayaran sudah diproses oleh mitra.

Contoh request

curl https://api.xendit.co/remittance_payouts/rpo_cde3dcb8-37d7-4ea1-a275-8f54af81feb0/cancel -X POST \
  -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:

Contoh response

{
  "id": "rpo_cde3dcb8-37d7-4ea1-a275-8f54af81feb0",
  "created": "2024-05-01T07:15:22Z",
  "updated": "2024-05-01T07:15:22Z",
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "49d056bd-21e5-4997-85f2-2127544c2196",
  "destination_currency": "PHP",
  "destination_amount": 35,
  "sender_customer_id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
  "recipient_customer_id": "cust-f71ffaa8-95a2-47ba-b486-cfe9e2c075d7",
  "status": "CANCELLED",
  "description": "This is a sample Cross-border Payout transaction",
  "source_of_fund": "OTHER",
  "origin_currency": "IDR",
  "origin_amount": "10000",
  "purpose_code": "OTHER",
  "relationship": "CUSTOMER",
  "failure_code": null,
  "metadata": {}
}

Penanganan Kesalahan

Kesalahan dalam membuat Cross-Border Payout

Semua kemungkinan error saat membuat Cross-Border Payout melalui endpoint API kami tercantum di bagian 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

INVALID_JSON_FORMAT

AMOUNT_FORMAT_ERROR

PAYMENT_CHANNEL_DETAIL_ERROR

Input tertentu tidak memenuhi persyaratan validasi API kami.

DUPLICATE_ERROR

Idempotency Key telah digunakan sebelumnya. Gunakan unik Idempotency Key dan coba lagi jika Anda ingin membuat transaksi baru.

DESTINATION_CURRENCY_NOT_SUPPORTED

Mata uang tujuan tidak didukung. Periksa apakah mata uang didukung untuk channel pilihan Anda sebelum mencoba 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 Pembayaran.

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.

ACCOUNT_BLACKLISTED_ERROR

Rekening bank penerima yang disediakan masuk daftar hitam.

PAYMENT_CHANNEL_DETAIL_ERROR

Jenis akun penerima yang disediakan tidak valid. Silakan gunakan nilai yang valid (BANK_ACCOUNT atau EWALLET).

Kesalahan Dalam Menjalankan Cross-Border Payout

Setelah status Cross-Border Payout adalah REQUESTED, status pembayaran dapat gagal dalam pemrosesan partner pembayaran kami atau ditolak oleh bank penerima, di mana statusnya akan beralih ke FAILED. Berlangganan remittance_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:

Kode kesalahan

Deskripsi

Haruskah Anda mencoba lagi?

INSUFFICIENT_BALANCE

Klien memiliki saldo yang tidak mencukupi untuk jumlah pembayaran

Ya, coba kembali pembayaran 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 pembayaran melebihi kemampuan penerima untuk menerima

Anda tidak mungkin berhasil jika mencoba kembali request payout. Harap konfirmasi dengan penerima apakah akun mereka dapat menerima pembayaran

REJECTED_BY_CHANNEL

Pembayaran 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 pembayaran 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 pembayaran dalam 1-3 jam

TRANSFER_ERROR

Kami mengalami error fatal saat memproses pembayaran 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 Cross-Border Payout

Pelajari lebih lanjut di bawah ini untuk berbagai event webhook yang dapat Anda langganan. Untuk informasi selengkapnya tentang status payout yang berbeda, lihat Payout Status Lifecycle.

event Webhook

Status Pembayaran

remittance_payout.succeeded

SUCCEEDED

remittance_payout.compliance_rejected

COMPLIANCE_REJECTED

remittance_payout.pending_compliance_assessment

PENDING_COMPLIANCE_ASSESSMENT

remittance_payout.failed

FAILED

remittance_payout.reversed

REVERSED