Request a Refund

The Refund Transaction endpoint allows merchants to request a refund for a transaction. Below is a step-by-step guide on how to request a refund through the API.

Refund Flow

1. Merchant → PagSeguro: The merchant requests a refund from PagSeguro using the Refund Transaction endpoint.
2. PagSeguro → Merchant: PagSeguro receives the request and returns a refund identifier (refund-id) to the merchant.
3. PagSeguro: PagSeguro processes the refund in coordination with the payment provider, using the data provided by the merchant.
4. PagSeguro → Merchant: PagSeguro notifies the merchant of the refund outcome, indicating whether it was successful or rejected.
5. Merchant: Upon receiving the result, the merchant may update the transaction in their system, retrieve additional transaction details via the API, or take further action based on the refund outcome.

📘

Refunds are asynchronous. You receive a refund-id immediately after requesting the refund, but the actual refund processing may take time depending on the payment method.

Refund Eligibility

To issue a refund, ensure:

• The transaction status is DELIVERED or COMPLETE.
• The payment method and country support refunds. Check the Available Payment Methods by Country for more details.
• The refund is requested within the allowed period. It is usually 90 days for credit cards.

To verify if a transaction is eligible for a refund via the API, check the refundable parameter in the response from the Transaction Search API. If refundable: true, the transaction can be refunded.

Examples

Send a POST request to /refunds with the required data. You must include a valid transaction-id, a notify-url, and optionally a reference and amount.

A successful refund request returns HTTP 201 Created and a refund ID

{
  "transaction-id": 123456789,
  "amount": 10.57,
  "notify-url": "https://virtualstore.com/notifications",
  "test-mode": 0,
  "reference": "REF-123456"
}

{
  "refund-id": 12345
}

Use this refund-id to track the refund status via notifications

💡

Omit amount for full refunds. Provide amount to process a partial refund.

Notifications

PagSeguro will POST a notification to the notify-url provided in your refund request once the refund is processed or rejected. The following code block shows an example of notification payload:

{
  "notification-type": "refund",
  "refund-id": 12345,
  "transaction-id": 75040384
}

You should then call the Transaction Search API to check the updated refund status.

📘

Refund Statuses

Access the (Refund Statuses)[ref:transaction-status-description#refund-statuses] for more details about the possible statuses.

Bank Deposit Refund Flow

Some payment methods (e.g., Boleto) require manual intervention from the end user. In such cases:

1. The user receives an email with a form link.
2. The user fills in personal and bank info for refund.
3. PagSeguro processes the bank transfer.
4. Merchant is notified via about the refund result.

⚠️

The user has 7 days to submit the form, or the refund is marked as REJECTED

📘

This flow may also apply to automatic payment methods, such as credit cards, especially when the refund is requested after the standard refund period has expired (typically 90 days).