Refund PIX charge

In this section, you will learn how to refund PIX charges that have been paid.

Available Endpoints

Sandbox: https://sandbox.pixtopay.com.br/v2/pix/refund
Production: https://api.pixtopay.com.br/v2/pix/refund

Refund charge

Processes a refund for a PIX charge that was paid. The refund is processed and the amount is returned to the payer.

Route

POST /v2/pix/refund

Headers

{
  "Authorization": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

Body Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Internal charge ID generated by PixToPay

Request example:

curl --location 'https://sandbox.pixtopay.com.br/v2/pix/refund' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "id": 59276
}'

Response `200` - Success:

{
  "id": 59276,
  "transaction_id": "12345678933",
  "status": 4,
  "currency": "BRL",
  "amount": 145,
  "refund_status": "processing"
}

Response Fields

Parameter	Type	Description
`id`	integer	Internal charge ID
`transaction_id`	string	Unique transaction identifier on your platform
`status`	integer	Charge status (will be 4 for refunded)
`currency`	string	Transaction currency
`amount`	number	Refunded amount
`refund_status`	string	Refund process status

Response `400` - Charge not found:

{
  "type": "ValidationError",
  "message": "Charge not found"
}

Response `400` - Charge not paid:

{
  "type": "ValidationError",
  "message": "Charge must be paid to be refunded"
}

Response `400` - Charge already refunded:

{
  "type": "ValidationError",
  "message": "Charge already refunded"
}

Important Notes

Only paid charges can be refunded: The charge must have status 1 (paid) to be refunded
Refunds are irreversible: Once a refund is requested, the process cannot be cancelled
Webhook: When the refund is completed, a webhook will be sent with the updated status 4 (refunded)
Timing: Refund timing may vary depending on the receiving bank

Status Flow

When you refund a charge, the status changes from:

1 (Paid) → 4 (Refunded)

Refund Webhook

When the refund is processed, you will receive a webhook at the configured endpoint with the following data:

{
  "id": 59276,
  "transaction_id": "12345678933",
  "status": 4,
  "event": "refund_completed",
  "amount": 145,
  "refunded_at": "2024-12-02T10:30:00.000Z"
}

Search Charges Cash-Out