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

Create a Cross-Border Payout

  • Updated on Jul 31, 2025
  • Published on Feb 11, 2025
Prev Next
Post
/remittance_payouts

Our Create Cross-Border Payout API allows you to send third party payouts from your Xendit Account on behalf of a sender to your designated recipient.

Security
HTTP
Type basic
Header parameters
Idempotency-key
stringRequired

A unique key to prevent processing duplicate requests. Can be your reference_id or any GUID.

Min length1
Max length100
Body parameters
createPayoutExample
{
  "reference_id": "myref-1482928194",
  "destination_currency": "IDR",
  "destination_amount": 1000000,
  "sender_customer_id": "cust-1752fefb-358c-4043-a690-58036157d851",
  "recipient_customer_id": "cust-b8476133-ec15-4f06-9dfb-562d8dca3f43",
  "origin_currency": "EUR",
  "origin_amount": 60,
  "source_of_fund": "OTHER",
  "purpose_code": "OTHER",
  "relationship": "CUSTOMER",
  "description": "This is a sample Cross-border Payout transaction"
}
Expand All
object
reference_id
string Required

A reference to uniquely identify the Payout.

Min length1
Max length255
Examplemyref-1482928194
destination_currency
string Required

ISO 4217 Currency Code.

destination_amount
number Required

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.0
sender_customer_id
string Required

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 Required

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

origin_currency
string Required

ISO 4217 Currency Code.

origin_amount
number Required

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.

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" ]
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" ]
description
string Required

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
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" }
Responses
200

Cross-Border Payout created

createCrossBorderPayoutResponseExample
{
  "id": "rpo_288250b4-124b-4be5-93a1-1cd50dd4ad02",
  "business_id": "665990ef233a8b8054549367",
  "description": "This is a sample Cross-border Payout transaction",
  "destination_amount": 1000000,
  "destination_currency": "IDR",
  "metadata": {},
  "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": "ACCEPTED",
  "created": "2024-12-13T07:51:10.832Z",
  "updated": "2024-12-13T07:51:10.832Z"
}
Expand All
object
id
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.0
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" }
400

Bad Request

OneOf
400APIValidationError
object (400APIValidationError)
error_code
string
ExampleAPI_VALIDATION_ERROR
error_message
string
ExampleInputs are failing validation. The errors field contains details about which fields are violating validation
400InvalidJSONFormatError
object (400InvalidJSONFormatError)
error_code
string
ExampleINVALID_JSON_FORMAT
error_message
string
ExampleThe request body is not a valid JSON format
400DestinationCurrencyNotSupportedError
object (400DestinationCurrencyNotSupportedError)
error_code
string
ExampleDESTINATION_CURRENCY_NOT_SUPPORTED
error_message
string
ExampleDestination currency is not supported. Check that the currency is supported for your chosen channel before retrying
400AmountFormatError
object (400AmountFormatError)
error_code
string
ExampleAMOUNT_FORMAT_ERROR
error_message
string
ExampleIncorrect number of decimal places for given amount
400MinimumTransferLimitError
object (400MinimumTransferLimitError)
error_code
string
ExampleMINIMUM_TRANSFER_LIMIT_ERROR
error_message
string
Example"amount” is under the minimum amount supported for the channel. See amount limitations at the URL below
400MaximumTransferLimitError
object (400MaximumTransferLimitError)
error_code
string
ExampleMAXIMUM_TRANSFER_LIMIT_ERROR
error_message
string
Example“amount” is more than the maximum amount supported for the channel. See amount limitations at the URL below
400AmountIncrementError
object (400AmountIncrementError)
error_code
string
ExampleAMOUNT_INCREMENT_NOT_SUPPORTED
error_message
string
Example“amount” needs to be a multiple of the minimum increment supported by the channel
400AccountBlacklistedError
object (400AccountBlacklistedError)
error_code
string
ExampleACCOUNT_BLACKLISTED_ERROR
error_message
string
ExampleThe provided recipient bank account is blacklisted
400PaymentChannelDetailError
object (400PaymentChannelDetailError)
error_code
string
ExamplePAYMENT_CHANNEL_DETAIL_ERROR
error_message
string
ExampleThe provided recipient account type is invalid. Please use the valid values (BANK_ACCOUNT or EWALLET)
400DuplicateError
object (400DuplicateError)
error_code
string
ExampleDUPLICATE_ERROR
error_message
string
ExampleA payout with this idempotency key already exists. If you meant to execute a different request, please use another idempotency key
403

Forbidden

OneOf
403RequestForbiddenError
object (403RequestForbiddenError)
error_code
string
ExampleREQUEST_FORBIDDEN_ERROR
error_message
string
ExampleThe API key is forbidden to perform this request
404

Not Found

OneOf
404CustomerDataNotFoundError
object (404CustomerDataNotFoundError)
error_code
string
ExampleCUSTOMER_DATA_NOT_FOUND
error_message
string
ExampleCould not find any customer object with given sender_customer_id or recipient_customer_id. Try again using a valid Customer Id
409

Conflict

OneOf
409IdempotencyError
object (409IdempotencyError)
error_code
string
ExampleIDEMPOTENCY_ERROR
error_message
string
ExampleKeys for idempotent requests can only be used for the same endpoint they were first used for. Try using a key if you meant to execute a different request
409StillProcessingError
object (409StillProcessingError)
error_code
string
ExampleSTILL_PROCESSING_ERROR
error_message
string
ExampleSimilar request with similar idempotency key is still processing
500

Internal Server Error

OneOf
500ServerError
object (500ServerError)
error_code
string
ExampleSERVER_ERROR
error_message
string
ExampleError connecting to our server. Retry safely using Idempotency-key header when available