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

Refund webhook notification

  • Updated on Oct 28, 2026
  • Published on Apr 9, 2025
Prev Next
Post
/your_refund_webhook_url

Webhook notification sent to your configured webhook URL when a refund succeeds or fails. Use data.refund_id and data.reference_id to match the notification to your refund. Verify the x-callback-token header and respond with HTTP 200 to acknowledge receipt.

Header parameters
x-callback-token
string

Your Xendit unique webhook token to verify the origin of the webhook. It is highly recommended for your integration to verify this value.

Body parameters

Refund status webhook notification

refundSucceeded
{
  "event": "refund.succeeded",
  "business_id": "62440e322008e87fb29c1fd0",
  "created": "2024-10-28T05:29:08.000Z",
  "api_version": "v3",
  "data": {
    "refund_id": "rfd-1402feb0-8b79-85ae-9d1e-e69394d3949c",
    "reference_id": "refund-order-123",
    "business_id": "62440e322008e87fb29c1fd0",
    "payment_id": "py-1402feb0-8b79-85ae-9d1e-e69394d3949c",
    "status": "SUCCEEDED",
    "amount": 10000,
    "currency": "IDR",
    "channel_code": "CARDS",
    "reason": "REQUESTED_BY_CUSTOMER",
    "created": "2024-10-28T05:29:07.000Z",
    "updated": "2024-10-28T05:29:07.000Z"
  }
}
object
event
string

refund.succeeded indicates that the refund completed successfully. refund.failed indicates that the refund could not be completed.

Valid values[ "refund.succeeded", "refund.failed" ]
business_id
string

Xendit-generated identifier for the business that owns the transaction

Example5f27a14a9bf05c73dd040bc8
created
string (date-time)

Timestamp when the webhook notification was created, in ISO 8601 date-time format.

Example2021-12-31T23:59:59Z
api_version
string

Version of the refund webhook payload.

Valid values[ "v3" ]
data
object (Payments_API_V3RefundSchema)

Details and current status of a V3 refund.

refund_id
string

Xendit-generated identifier for a refund.

Pattern^rfd-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Examplerfd-1402feb0-8b79-85ae-9d1e-e69394d3949c
reference_id
string

A Reference ID from merchants to identify their request.

Min length1
Max length255
business_id
string

Xendit-generated identifier for the business that owns the transaction

Example5f27a14a9bf05c73dd040bc8
payment_id
string

Xendit unique Payment ID generated as reference for a payment.

Examplepy-1402feb0-bb79-47ae-9d1e-e69394d3949c
status
string

PENDING: the refund is still processing. SUCCEEDED: the refund completed successfully. FAILED: the refund could not be completed; check failure_code for details.

Valid values[ "SUCCEEDED", "FAILED", "PENDING" ]
amount
number

The intended payment amount to be refunded to the end user.

Exclusive minimum0.0
Example10000
currency
string

ISO 4217 three-letter currency code for the payment.

Valid values[ "IDR", "PHP", "VND", "THB", "SGD", "MYR", "USD", "HKD", "AUD", "GBP", "EUR", "JPY", "MXN", "AED", "AFN", "ALL", "AMD", "AOA", "ARS", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "FJD", "FKP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HNL", "HTG", "HUF", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SHP", "SLE", "SOS", "SRD", "SSP", "STN", "SVC", "SYP", "SZL", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "UYU", "UZS", "VEF", "VES", "VUV", "WST", "XAF", "XCD", "XCG", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWG", "ZWL" ]
ExampleIDR
channel_code
string

Channel code used to select the payment method provider.

reason
string

Reason for requesting the refund.

Valid values[ "FRAUDULENT", "DUPLICATE", "REQUESTED_BY_CUSTOMER", "CANCELLATION", "OTHERS" ]
created
string (date-time)

ISO 8601 date-time format.

Example2021-12-31T23:59:59Z
updated
string (date-time)

ISO 8601 date-time format.

Example2021-12-31T23:59:59Z
failure_code
string | null

Channel-specific failure code if the refund fails; otherwise null or omitted.

refund_details
object (Payments_API_RefundDetails)

Additional refund information, when available from the channel.

acquirer_reference_id
string | null

Reference provided by the acquirer to help trace the refund.

metadata
object (Payments_API_RefundMetadata)

Custom data attached to the refund. Supports up to 50 entries. Keys must be no longer than 40 characters. Values may be strings (up to 500 characters), finite numbers, booleans, or null. Nested objects and arrays are not supported.

Example{ "order_id": "1234567890" }
property*
AnyOf
string
string
Max length500
number
number
boolean
boolean
Responses
200

Webhook notification acknowledged.