For archived content, access the previous documentation here or the previous API reference here.

Cross-border payout webhook

Post

/cross_border_payout_webhook_url

Xendit notifies your system change of status of your payout link via webhook. You need to provide an URL to receive webhook. Please specify your URL in Webhook Settings in Xendit Dashboard.

The Cross-Border Payout notification will be sent as POST request to the URL you set. Xendit attach x-callback-token header that you can validate against Verification Token in Webhook Settings to verify message authenticity.

Please response back with status 200 immediately. Xendit marks webhook event as failed if there is no response within 30s. When events failed, automatic retry will kick-off for the next 24h. Alternatively, you can resend any event in Webhook tab at anytime. You can also receive notification via email every 6h to check your webhook health.

Security

HTTP

Type basic

Responses

200

Cross-Border Payout Webhook

crossBorderPayoutWebhookExample

{
  "event": "remittance_payout.pending_compliance_assessment",
  "id": "rpo_288250b4-124b-4be5-93a1-1cd50dd4ad02",
  "created": "2024-12-13T07:51:10.832Z",
  "updated": "2024-12-13T07:51:10.832Z",
  "business_id": "665990ef233a8b8054549367",
  "description": "This is a sample Cross-border Payout transaction",
  "destination_amount": 1000000,
  "destination_currency": "IDR",
  "origin_amount": 60,
  "origin_currency": "EUR",
  "purpose_code": "OTHER",
  "recipient_customer_id": "cust-b8476133-ec15-4f06-9dfb-562d8dca3f43",
  "reference_id": "myref-1482928194",
  "relationship": "CUSTOMER",
  "sender_customer_id": "cust-1752fefb-358c-4043-a690-58036157d851",
  "source_of_fund": "OTHER",
  "status": "PENDING_COMPLIANCE_ASSESSMENT",
  "metadata": {}
}

Expand All

object

event

string

Type of the event:

remittance_payout.pending_compliance_assessment - Request is considered medium or high risk, and is being reviewed by our compliance team. Our team will contact you via email for extra information for enhanced due diligence.
remittance_payout.compliance_rejected - Request is rejected for compliance reasons.
remittance_payout.failed - Payout failed. See possible reasons in Failed Reasons section.
remittance_payout.succeeded - Sender bank/channel has sent out the payout
remittance_payout.ready - For cash payout only. Cash is ready for pick-up.
remittance_payout.locked - For cash payout only. Cash pick-up in progress.
remittance_payout.expired - For cash payout only. Cash payout has expired.

Valid values[ "remittance_payout.pending_compliance_assessment", "remittance_payout.compliance_rejected", "remittance_payout.failed", "remittance_payout.succeeded", "remittance_payout.ready", "remittance_payout.locked", "remittance_payout.expired" ]

disbursement_code

string

Only for event remittance_payout.ready Code to be presented by the beneficiary for cash pick-up. Please share this with the beneficiary.

Min length1

Max length100

ExampleXENDIT-12341

string

Xendit-generated unique payout link id in UUID format

Prefix: rpo_

Min length40

Max length40

Examplerpo_cde3dcb8-37d7-4ea1-a275-8f54af81feb0

created

string

Timestamp when the payout request was made (in ISO 8601 format)

Timezone UTC+0

updated

string

Timestamp when the payout request was updated (in ISO 8601 format)

Timezone UTC+0

business_id

string

Your Xendit Business ID

Example5785e6334d7b410667d355c4

reference_id

string

A reference to uniquely identify the Payout.

Min length1

Max length255

Examplemyref-1482928194

destination_currency

string

ISO 4217 Currency Code.

destination_amount

number

Amount to be sent to the destination account.

For IDR currency, number should be integer
For PHP currency, number can be up to 2 decimal places
For VND currency, number should be integer
For MYR currency, number can be up to 2 decimal places
For THB currency, number can be up to 2 decimal places

Minimum0.0

Example10000

sender_customer_id

string

The Id of the sender customer (as returned by the Create Customer endpoint)

The following fields are required in the sender customer object: customer_type and addresses

For INDIVIDUAL customer_type, the following parameters are also required: given_names, nationality, and date_of_birth in customer_type.individual_detail object
For BUSINESS customer_type, then the following parameters are also required: business_name in customer_type.business_detail object.
For addresses object, the following fields are also required: addresses.country, addresses.city, addresses.street_line1

Reference: Customer Object

recipient_customer_id

string

The Id of the recipient customer (as returned by the Create Customer endpoint)

The following fields are required in the sender customer object: customer_type, addresses, identity_accounts, and one of phone_number or mobile_number

For INDIVIDUAL customer_type, the following parameters are also required: given_names, nationality, and date_of_birth in customer_type.individual_detail object
For BUSINESS customer_type, then the following parameters are also required: business_name in customer_type.business_detail object.
For addresses object, the following fields are also required: addresses.country, addresses.city, addresses.street_line1
For identity_accounts object, the following fields are also required: type, country, company (with the channel code value), and properties

Reference: Customer Object

status

string

Status of the cross-border payout. Default is ACCEPTED.

ACCEPTED - The payout request has been accepted and has not yet been sent on to a channel. A payout may remain in this status if the chosen channel is currently offline. Xendit will process this automatically when the channel comes back online
PENDING_COMPLIANCE_ASSESSMENT - Request is considered medium or high risk, and is being reviewed by our compliance team. Our team will contact you via email for extra information for enhanced due diligence.
COMPLIANCE_REJECTED - Request is rejected for compliance reasons.
REQUESTED - The payout has been sent to the channel. Funds have been sent to the channel for processing.
READY - For cash payout only. Cash is ready for pick-up.
LOCKED - For cash payout only. Cash pick-up in progress.
EXPIRED - For cash payout only. Cash payout has expired.
FAILED - Payout failed. See possible reasons in Failed Reasons section.
SUCCEEDED - Sender bank/channel has sent out the payout
CANCELLED - Payout has been cancelled per your request
REFUNDED - Only valid for SKN/RTGS and cash channel use case.

Valid values[ "ACCEPTED", "PENDING_COMPLIANCE_ASSESSMENT", "COMPLIANCE_REJECTED", "REQUESTED", "READY", "LOCKED", "EXPIRED", "FAILED", "SUCCEEDED", "CANCELLED", "REFUNDED" ]

description

string

Description to send with the payout. The recipient may see this e.g. in their bank statement (if supported) or in email receipts we send on your behalf.

Min length1

Max length100

source_of_fund

string

Source of fund

INVESTMENT - Bonds, fixed deposits, preference shares, business ownership/equity or property ownership
PERSONAL_SAVINGS - Funds kept in an account in a bank or a similar organization
BUSINESS_REVENUE - Income from a business or a company
LEGACY - Inherited money from a will
BUSINESS_ARRANGEMENT - Any understanding, procedure, course of dealing, or arrangement between a creditor and a seller
LOAN - A sum of money that is borrowed
SALARY - A fixed regular payment made by an employer
OTHER - Other

Default: OTHER

Valid values[ "INVESTMENT", "PERSONAL_SAVINGS", "BUSINESS_REVENUE", "LEGACY", "BUSINESS_ARRANGEMENT", "LOAN", "SALARY", "OTHER" ]

origin_currency

string

ISO 4217 Currency Code.

origin_amount

number

The original amount as sent by the sender. This field will not be used for processing the payout, but is required for monitoring purposes.

Xendit will deduct your balance and process the payout in the destination amount and currency.

purpose_code

string

Purpose of the Cross-border Payout

SELF - Transfer to own account
FAMILY - Family Maintenance
EDUCATION - Education-related student expenses
MEDICAL - Medical Treatment
HOTEL - Hotel Accomodation
TRAVEL - Travel
UTILITIES - Utility Bills
LOAN_REPAYMENT - Repayment of Loans
TAX_PAYMENT - Tax Payment
RESIDENCE_PURCHASE - Purchase of Residential Property
RESIDENCE_RENT - Payment of Property Rental
INSURANCE - Insurance
MUTUAL_FUND - Mutual Fund Investment
SHARES_INVESTMENT - Investment in Shares
DONATIONS - Donations
ADVERTISING - Advertising & Public relations-related expenses
ROYALTY_FEES - Royalty fees, trademark fees, patent fees, and copyright fees
BROKER_FEES - Fees for brokers, front end fee, commitment fee, guarantee fee and custodian fee
ADVISORS - Fees for advisors, technical assistance, and academic purpose, including remuneration for specialists
OFFICE - Representative office expenses
CONSTRUCTION - Construction costs / expenses
SHIPMENT - Transportation fees for goods
EXPORT - For payment of exported goods
DELIVERY - Delivery fees for goods
TRADES - General Goods Trades - Offline trade
SALARY - Salary
REFUND - Refund
OTHER - Other

Default: OTHER

Valid values[ "SELF", "FAMILY", "EDUCATION", "MEDICAL", "HOTEL", "TRAVEL", "UTILITIES", "LOAN_REPAYMENT", "TAX_PAYMENT", "RESIDENCE_PURCHASE", "RESIDENCE_RENT", "INSURANCE", "MUTUAL_FUND", "SHARES_INVESTMENT", "DONATIONS", "ADVERTISING", "ROYALTY_FEES", "BROKER_FEES", "ADVISORS", "OFFICE", "CONSTRUCTION", "SHIPMENT", "EXPORT", "DELIVERY", "TRADES", "SALARY", "REFUND", "OTHER" ]

relationship

string

Relationship between sender and recipient

Required for PH_GCASH Default: OTHER

Valid values[ "BRANCH_REPRESENTATIVE_OFFICE", "BUSINESS_PARTNER", "CHILDREN", "CREDITOR", "CUSTOMER", "DEBTOR", "EMPLOYEE", "EX_SPOUSE", "FRANCHISEE_FRANCHISOR", "GRANDPARENTS", "HOLDING_COMPANY", "MAID", "OWNSELF", "PARENTS", "RELATIVE", "SIBLING", "SPOUSE", "SUBSIDIARY_COMPANY", "SUPPLIER", "FRIEND", "GOVERNMENT_BODY", "EDUCATION_INSTITUTION", "NON_GOVERNMENT_BODY", "OTHER" ]

failure_code

string

If the Payout failed, we include a failure code for more details on the failure.

INSUFFICIENT_BALANCE - Client has insufficient balance for the payout amount
INVALID_DESTINATION - The recipient account does not exist/is invalid.
REJECTED_BY_CHANNEL - Payout failed due to an error from the destination channel. This is usually because of network issues associated with the destination bank or issues crediting funds into the destination bank account.
TEMPORARY_TRANSFER_ERROR - The channel networks are experiencing a temporary error.
TRANSFER_ERROR - We’ve encountered a fatal error while processing this payout. Normally, this means that certain API fields in your request are invalid.
UNKNOWN_BANK_NETWORK_ERROR - The bank has delivered an error they have not documented. By definition, this means the bank does not know the issue.
DESTINATION_MAXIMUM_LIMIT - The recipient is unable to receive the funds due to the payout amount exceeding the recipient’s ability to receive.

Valid values[ "INSUFFICIENT_BALANCE", "INVALID_DESTINATION", "REJECTED_BY_CHANNEL", "TEMPORARY_TRANSFER_ERROR", "TRANSFER_ERROR", "UNKNOWN_BANK_NETWORK_ERROR", "DESTINATION_MAXIMUM_LIMIT" ]

metadata

object (Metadata) | null

Key-value entries for your custom data. You can specify up to 50 keys, with key names up to 40 characters and values up to 500 characters. This is for your convenience. Xendit will not use this data for any processing.

Example{ "my_custom_id": "merchant-123", "my_custom_order_id": "order-123" }

Was this article helpful?