API - Pix Refund

This endpoint processes refunds for previously completed transactions from PIX. It supports both full and partial refunds.

POST {BASE_URL}/wipay-payment-admin/v2/refund

Headers

Header	Required	Description	Example
Authorization	Yes	Bearer token for authentication	Bearer...
x-api-key	Yes	API key for service access	xxxxxxxxxxxxxxxxxx
Content-Type	Yes	Must be application/json	application/json

Body Parameters

Parameter	Type	Required	Description	Validation
requestId	string	Yes	Original transaction ID to refund	Valid UUID format
amount	number	Yes	Refund amount (partial or full)	Positive decimal ≤ original amount
reference	string	Yes	Original transaction reference	Alphanumeric string
terminalId	string	No	Terminal identifier	Optional
merchantOperationId	string	No	Merchant's internal reference	Optional tracking ID

Example Request

{
    "requestId": "5334400136-25-0-NXh8AAX7qSjwmKbgkm9Vy6Ya",
    "amount": 1.50,
    "reference": "E99999999999999999999s9999a9e99f",
    "terminalId": "terminal-001",
    "merchantOperationId": "REFUND-0042"
}

Response

200

{
    "successful": true,
    "originalRequestId": "5334400136-25-0-NXh8AAX7qSjwmKbgkm9Vy6Ya",
    "refundId": "5334400136-25-0-dqauhN7XGgNfEoaekHfDI1ca",
    "originalReference": "E99999999999999999999s9999a9e99f",
    "refundReference": "5334400136-25-0-NXh8AAX7qSjwmKbgkm9Vy6Ya",
    "amount": 1.50,
    "requestDate": "2025-10-27T13:47:10.971326585Z"
}

400

Response Fields

Field	Type	Description
successful	boolean	Indicates if the refund was successfully initiated
originalRequestId	string	Original transaction ID that was refunded
refundId	string	Unique identifier for the refund transaction
originalReference	string	Reference of the original transaction
refundReference	string	Reference for the refund operation
amount	number	Refunded amount
requestDate	string	Refund request timestamp (ISO 8601 format)