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

List refunds for a payment

Published on Oct 28, 2026

Get

/v3/refunds

Retrieve refunds for a V3 payment using its payment_id (py- prefix). Legacy payment IDs are not supported by this endpoint. The response is an array of refund objects.

Security

HTTP

Type basic

Header parameters

api-version

stringRequired

API version required for V3 refund operations.

Valid values[ "2024-11-11" ]

for-user-id

string

The XenPlatform subaccount user id that will perform this transaction.

Query parameters

payment_id

stringRequired

V3 payment ID whose refunds you want to retrieve.

Min length1

Examplepy-1402feb0-8b79-85ae-9d1e-e69394d3949c

Responses

200

Refunds for the specified payment.

Refunds

[
  {
    "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"
    }
  }
]

Array of object

object

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

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

Max length500

number

boolean

400

Bad request

OneOf

Payments_API_Http400InvalidValueError

object (Payments_API_Http400InvalidValueError)

error_code

string

Valid values[ "INVALID_VALUE_ERROR" ]

message

string

Values in the payment request is not within expected range or expected configurations. Check the specific error message for debugging.

Payments_API_Http400ApiValidationError

object (Payments_API_Http400ApiValidationError)

error_code

string

Valid values[ "API_VALIDATION_ERROR" ]

message

string

Fields or values in the payment request does not comply with our API specification. Check the specific error message for debugging.

Payments_API_Http400RefundNotSupported

object (Payments_API_Http400RefundNotSupported)

error_code

string

Valid values[ "REFUND_NOT_SUPPORTED" ]

message

string

Refund feature is not available for this payment channel.

401

Unauthorized

OneOf

Payments_API_Http401InvalidApiKey

object (Payments_API_Http401InvalidApiKey)

error_code

string

Valid values[ "INVALID_API_KEY" ]

message

string

The API key is missing or invalid. Use a valid secret API key to authenticate the request.

404

Not found

OneOf

Payments_API_Http404DataNotFound

object (Payments_API_Http404DataNotFound)

error_code

string

Valid values[ "DATA_NOT_FOUND" ]

message

string

ID specified in request cannot be found.

500

Internal server error

OneOf

Payments_API_Http500ServerError

object (Payments_API_Http500ServerError)

error_code

string

Valid values[ "SERVER_ERROR" ]

message

string

An unexpected error occured, our team has been notified and will troubleshoot the issue

503

Service unavailable

OneOf

Payments_API_Http503ChannelUnavailable

object (Payments_API_Http503ChannelUnavailable)

error_code

string

Valid values[ "CHANNEL_UNAVAILABLE" ]

message

string

The channel requested is currently experiencing unexpected issues. The provider will be notified to resolve this issue.

Was this article helpful?