> ## Documentation Index > Fetch the complete documentation index at: https://docs.xendit.co/llms.txt > Use this file to discover all available pages before exploring further. # Refund webhook notification > 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. ## OpenAPI ````json POST /your_refund_webhook_url { "openapi": "3.0.0", "info": { "title": "Payments", "version": "3.0.0", "description": "Payments API enables businesses to integrate seamless and secure payment processing into their platforms, \nsupporting key features like a customizable checkout page for user-friendly payment experiences, \ndirect payments through API for tailored and flexible transaction flows, \nand recurring subscriptions to automate billing for memberships or SaaS. \nThese APIs streamline payment processing by supporting multiple payment channels, \nensuring PCI compliance, and offering features like tokenization, real-time transactions, \nand automated retries for subscription payments, making them essential for modern, scalable businesses.\n" }, "servers": [ { "url": "https://api.xendit.co", "description": "Xendit API" } ], "tags": [ { "name": "Payment Request", "x-displayName": "Payment Request" }, { "name": "Refund", "x-displayName": "Refund" }, { "name": "Payment", "x-displayName": "Payment" }, { "name": "Payment Token", "x-displayName": "Payment Token" }, { "name": "Subscriptions", "description": "Manage recurring plans and cycles", "x-displayName": "Subscriptions" }, { "name": "Session", "x-displayName": "Session" }, { "name": "Disputes", "description": "Core dispute management endpoints", "x-displayName": "Disputes" } ], "paths": { "/your_refund_webhook_url": { "post": { "operationId": "RefundWebhook", "summary": "Refund webhook notification", "description": "Webhook notification sent to your configured webhook URL when a refund succeeds or fails.\nUse `data.refund_id` and `data.reference_id` to match the notification to your refund.\nVerify the `x-callback-token` header and respond with HTTP 200 to acknowledge receipt.\n", "parameters": [ { "$ref": "#/components/parameters/Payments_API_XCallbackToken" } ], "tags": [ "Refund" ], "requestBody": { "required": true, "description": "Refund status webhook notification", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "refund.succeeded", "refund.failed" ], "description": "`refund.succeeded` indicates that the refund completed successfully.\n`refund.failed` indicates that the refund could not be completed.\n" }, "business_id": { "$ref": "#/components/schemas/Payments_API_BusinessId" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the webhook notification was created, in ISO 8601 date-time format.\n", "example": "2021-12-31T23:59:59Z" }, "api_version": { "type": "string", "enum": [ "v3" ], "description": "Version of the refund webhook payload." }, "data": { "$ref": "#/components/schemas/Payments_API_V3RefundSchema" } } }, "examples": { "refundSucceeded": { "value": { "event": "refund.succeeded", "business_id": "62440e322008e87fb29c1fd0", "created": "2024-10-28T05:29:08Z", "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:07Z", "updated": "2024-10-28T05:29:07Z" } } } } } } }, "responses": { "200": { "description": "Webhook notification acknowledged." } } } } }, "components": { "parameters": { "Payments_API_XCallbackToken": { "in": "header", "name": "x-callback-token", "required": false, "schema": { "type": "string" }, "description": "Your Xendit unique webhook token to verify the origin of the webhook. It is highly recommended for your integration to verify this value." } }, "schemas": { "Payments_API_BusinessId": { "type": "string", "description": "Xendit-generated identifier for the business that owns the transaction", "example": "5f27a14a9bf05c73dd040bc8" }, "Payments_API_V3RefundSchema": { "type": "object", "description": "Details and current status of a V3 refund.", "properties": { "refund_id": { "$ref": "#/components/schemas/Payments_API_RefundId" }, "reference_id": { "$ref": "#/components/schemas/Payments_API_ReferenceId" }, "business_id": { "$ref": "#/components/schemas/Payments_API_BusinessId" }, "payment_id": { "$ref": "#/components/schemas/Payments_API_PaymentId" }, "status": { "$ref": "#/components/schemas/Payments_API_V3RefundStatus" }, "amount": { "$ref": "#/components/schemas/Payments_API_RefundAmount" }, "currency": { "$ref": "#/components/schemas/Payments_API_Currency" }, "channel_code": { "$ref": "#/components/schemas/Payments_API_ChannelCode" }, "reason": { "$ref": "#/components/schemas/Payments_API_V3RefundReason" }, "created": { "$ref": "#/components/schemas/Payments_API_CreatedDateTime" }, "updated": { "$ref": "#/components/schemas/Payments_API_UpdatedDateTime" }, "failure_code": { "$ref": "#/components/schemas/Payments_API_RefundFailureCode" }, "refund_details": { "$ref": "#/components/schemas/Payments_API_RefundDetails" }, "metadata": { "$ref": "#/components/schemas/Payments_API_RefundMetadata" } } }, "Payments_API_RefundId": { "type": "string", "pattern": "^rfd-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Xendit-generated identifier for a refund.", "example": "rfd-1402feb0-8b79-85ae-9d1e-e69394d3949c" }, "Payments_API_ReferenceId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "A Reference ID from merchants to identify their request." }, "Payments_API_PaymentId": { "type": "string", "description": "Xendit unique Payment ID generated as reference for a payment.", "example": "py-1402feb0-bb79-47ae-9d1e-e69394d3949c" }, "Payments_API_V3RefundStatus": { "type": "string", "enum": [ "SUCCEEDED", "FAILED", "PENDING" ], "description": "`PENDING`: the refund is still processing.\n`SUCCEEDED`: the refund completed successfully.\n`FAILED`: the refund could not be completed; check `failure_code` for details.\n" }, "Payments_API_RefundAmount": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "The intended payment amount to be refunded to the end user.\n", "example": 10000 }, "Payments_API_Currency": { "type": "string", "enum": [ "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" ], "description": "ISO 4217 three-letter currency code for the payment.", "example": "IDR" }, "Payments_API_ChannelCode": { "type": "string", "description": "Channel code used to select the payment method provider.\n\n\n" }, "Payments_API_V3RefundReason": { "type": "string", "enum": [ "FRAUDULENT", "DUPLICATE", "REQUESTED_BY_CUSTOMER", "CANCELLATION", "OTHERS" ], "description": "Reason for requesting the refund." }, "Payments_API_CreatedDateTime": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time format.\n", "example": "2021-12-31T23:59:59Z" }, "Payments_API_UpdatedDateTime": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time format.\n", "example": "2021-12-31T23:59:59Z" }, "Payments_API_RefundFailureCode": { "type": "string", "nullable": true, "description": "Channel-specific failure code if the refund fails; otherwise null or omitted." }, "Payments_API_RefundDetails": { "type": "object", "description": "Additional refund information, when available from the channel.", "properties": { "acquirer_reference_id": { "type": "string", "nullable": true, "description": "Reference provided by the acquirer to help trace the refund." } } }, "Payments_API_RefundMetadata": { "type": "object", "maxProperties": 50, "description": "Custom data attached to the refund. Supports up to 50 entries. Keys must be\nno longer than 40 characters. Values may be strings (up to 500 characters),\nfinite numbers, booleans, or null. Nested objects and arrays are not supported.\n", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500, "nullable": true }, { "type": "number" }, { "type": "boolean" } ] }, "example": { "order_id": "1234567890" } } } } } ````