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

Payout webhook

Post

/payout_webhook_url

Xendit notifies your system upon failed and successful payouts via webhook. You need to provide an URL to receive webhook. Please specify your URL in Webhook Settings in Xendit Dashboard.

The payment 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

Payout Webhook

payoutWebhookExample

{
  "event": "payout.succeeded",
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "created": "2025-01-01T23:55:59Z",
  "data": {
    "id": "disb-571f3644d2b4edf0745e9703",
    "amount": 10000,
    "channel_code": "ID_BCA",
    "currency": "IDR",
    "status": "SUCCEEDED",
    "description": "July payout",
    "reference_id": "myref-1482928194",
    "created": "2024-12-31T23:53:59Z",
    "updated": "2024-12-31T23:53:59Z",
    "estimated_arrival_time": "2024-12-31T23:59:59Z",
    "business_id": "6018306aa16ad90cb3c43ba7",
    "channel_properties": {
      "account_number": "000000000099",
      "account_holder_name": "Michael Chen"
    }
  }
}

Expand All

object

event

string

Type of the event:

payout.succeeded - A payout's status has already succeeded and partner bank has credited the funds to the beneficiary
payout.failed - A payout's status has already failed and the partner bank rejected the transaction or there was an issue processing the transaction
payout.reversed - A payout that was originally in succeeded status received a bounceback or reversal of funds from the partner bank. Funds have been refunded back to the merchant’s available balance.

Valid values[ "payout.succeeded", "payout.failed", "payout.reversed" ]

business_id

string

Your Xendit Business ID

Example5785e6334d7b410667d355c4

created

string

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

Timezone UTC+0

data

object (StandardPayoutResponseSchema)

string

Xendit-generated unique identifier for each payout

Prefix: disb_

Min length29

Max length29

Exampledisb-571f3644d2b4edf0745e9703

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

channel_code

string

Channel code of destination bank, E-Wallet or OTC channel. List of supported channels can be found here

ExampleID_BCA

currency

string

ISO 4217 Currency Code.

reference_id

string

A reference to uniquely identify the Payout.

Min length1

Max length255

Examplemyref-1482928194

status

string

Status of the payout.

The status in the response will always be ACCEPTED; meaning transfer is initiated but not yet completed by bank or E-Wallet. The final status will be given in a callback.

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
REQUESTED - The payout has been sent to the channel. Funds have been sent to the channel for processing.
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
REVERSED - Payout was rejected by the channel after the payout succeeded. Commonly due to invalid or dormant account.

Valid values[ "ACCEPTED", "REQUESTED", "FAILED", "SUCCEEDED", "CANCELLED", "REVERSED" ]

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

estimated_arrival_time

string

Estimated time of arrival of funds in destination account (in ISO 8601 format) For OTC payouts: Estimated time that funds will be available for pick-up

Timezone UTC+0

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" ]

business_id

string

Your Xendit Business ID

Example5785e6334d7b410667d355c4

channel_properties

object (ChannelProperties)

account_holder_name

string

Name of account holder as per the bank or E-Wallet's records. Needs to match the registered account name exactly.

Min length1

Max length100

account_number

string

Account number of destination. Mobile numbers for E-Wallet accounts. For E-Wallets, standard format should use prefix 0, e.g. 081234567890

Min length1

Max length100

account_type

string

Account type of the destination for currencies and channels that supports proxy transfers (ie: Using mobile number as account number) If you do not specify a value for this field, the default value is BANK_ACCOUNT

Values:

For channel_code == MY_DUITNOW: MOBILE_NO NATIONAL_ID PASSPORT BUSINESS_REGISTRATION BANK_ACCOUNT

For currency == THB: MOBILE_NO NATIONAL_ID BANK_ACCOUNT

receipt_notification

object (ReceiptNotification)

Object containing email addresses to receive payout details upon successful Payout. Maximum of three email addresses each.

email_to

Array of string

Direct email recipients

string

email_cc

Array of string

CC-ed email recipients

string

email_bcc

Array of string

BCC-ed email recipients

string

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?