Refund a payment using its payment_id. Refunds are available for eligible card,
e-wallet, direct debit, and QR code payments, subject to channel support.
Provide amount for a specific refund amount, or omit it to request a full refund.
The amount uses the original payment's currency. Partial refunds depend on channel support.
Use a new reference_id to identify each refund in your system.
Check status in the response. If it is PENDING, wait for the refund status
webhook or retrieve the refund by its refund_id to check for a final status.
API version required for V3 refund operations.
The XenPlatform subaccount user id that will perform this transaction.
Refund a specified amount
{
"reference_id": "refund-order-123",
"payment_id": "py-1402feb0-8b79-85ae-9d1e-e69394d3949c",
"amount": 10000,
"reason": "REQUESTED_BY_CUSTOMER",
"metadata": {
"order_id": "1234567890"
}
}Request a full refund
{
"reference_id": "refund-order-124",
"payment_id": "py-1402feb0-8b79-85ae-9d1e-e69394d3949c",
"reason": "REQUESTED_BY_CUSTOMER"
}Request a refund for an existing payment.
A Reference ID from merchants to identify their request.
ID of the original payment to refund. Accepts V3 payment IDs (py-) and
supported legacy payment IDs: card IDs (ca_, cc_, or a 24-character
hexadecimal ID), e-wallet IDs (ewc_), direct debit IDs (ddpy_), and QR IDs (qrpy_).
Use the payment ID, not the payment request ID.
Amount to refund in the original payment's currency. Must be greater than zero. Omit to request a full refund. Partial refunds depend on channel support.
Reason for requesting the refund.
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.
Refund request processed. Check status to determine whether the refund is pending, succeeded, or failed.
{
"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",
"metadata": {
"order_id": "1234567890"
}
}Details and current status of a V3 refund.
Xendit-generated identifier for a refund.
A Reference ID from merchants to identify their request.
Xendit-generated identifier for the business that owns the transaction
Xendit unique Payment ID generated as reference for a payment.
PENDING: the refund is still processing.
SUCCEEDED: the refund completed successfully.
FAILED: the refund could not be completed; check failure_code for details.
The intended payment amount to be refunded to the end user.
ISO 4217 three-letter currency code for the payment.
Channel code used to select the payment method provider.
Reason for requesting the refund.
ISO 8601 date-time format.
ISO 8601 date-time format.
Channel-specific failure code if the refund fails; otherwise null or omitted.
Additional refund information, when available from the channel.
Reference provided by the acquirer to help trace the refund.
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.
Bad request
Values in the payment request is not within expected range or expected configurations. Check the specific error message for debugging.
Fields or values in the payment request does not comply with our API specification. Check the specific error message for debugging.
Refund feature is not available for this payment channel.
Refund amount specified in refund request must be less than or equal to unrefunded capture amount.
Please wait for the pending refund request to be completed before initiating a new one.
There is insufficient balance in your account to perform a refund. Please top up your balance with a sufficient amount before retrying the refund.
Number of partial refunds for this payment request has exceeded what is allowed by payment channel. Please check our documentations for refund limitations.
Feature is not allowed for the payment request because of its current status. Check the specific error message for debugging.
The maximum refundable amount for this payment has been reached.
The maximum number of refunds allowed for this payment has been reached.
Partial refunds are not supported for this payment or channel.
Refunds are temporarily unavailable for this payment or channel. Try again later.
Unauthorized
The API key is missing or invalid. Use a valid secret API key to authenticate the request.
Forbidden
Feature is not allowed for the payment request because of its current status. Check the specific error message for debugging.
Merchant credentials met with an error with the provider. Please contact Xendit customer support to resolve this issue.
Refund feature is not available for this payment channel.
Partial Refund feature is not available for this payment channel.
This payment is not eligible for a refund. Check the error message for details.
Not found
ID specified in request cannot be found.
Conflict
Duplication is not allowed. Check specific error message for debugging.
Internal server error
An unexpected error occured, our team has been notified and will troubleshoot the issue
Service unavailable
The channel requested is currently experiencing unexpected issues. The provider will be notified to resolve this issue.