The Refund a Transaction endpoint allows merchants to request a full or partial refund for a transaction.

Refund Flow

1. Merchant → PagSeguro: Merchant requests a refund from PagSeguro.
2. PagSeguro → Merchant: PagSeguro receives the data and returns the refund identifier to the Merchant.
3. PagSeguro: PagSeguro processes the data transferred by the Merchant.
4. PagSeguro → Merchant: PagSeguro notifies the Merchant of the transaction status change.
5. Merchant: Merchant receives the notification and updates the order status.

Refund Eligibility

Check the refundable field in the Search Transaction Using Transaction Code endpoint:

• true→ refundable
• false→ not refundable

Also validate supported payment methods by country Payment Methods Available by Country .

Refund Types

Full Refund

A full refund returns the entire transaction amount, including additional charges.

Partial Refund

A partial refund returns only part of the transaction amount.

• Multiple partial refunds are allowed
• The total refunded amount must not exceed the total transaction amount

Request Parameters

👉 Important:
The reference must be the code returned by PagSeguro at the time of payment creation.
It is not a merchant-defined reference.

Examples

To request a refund for a transaction, make a request to the Refund a Transaction endpoint, as shown in the example below.

The response will contain details about the refund request, such as ID, amount, and status.

Full Refund

{
    "notification_url": "https://www.merchantwebsite.com/notify?type=refund",
    "amount": 103.5,
    "reference": "REF-XXX-1234567890"
}

{
    "id": 35,
    "reference": "REF-XXX-1234567890",
    "amount": 103.5,
    "status": "requested",
    "created_at": "2021-04-12T11:16:55Z",
    "updated_at": "2021-04-12T11:16:55Z"
}

Partial Refund

{
    "notification_url": "https://www.merchantwebsite.com/notify?type=refund",
    "amount": 50.0,
    "reference": "REF-XXX-1234567890"
}

{
    "id": 35,
    "reference": "REF-XXX-1234567890",
    "amount": 50.0,
    "status": "requested",
    "created_at": "2021-04-12T11:16:55Z",
    "updated_at": "2021-04-12T11:16:55Z"
}

👉 In this scenario:

• Refunded amount: 50.00
• Remaining refundable amount: 53.50

✅ The merchant can still request additional refunds up to the remaining 53.50, including a refund of the full remaining balance.

Response

A successful request returns:

• id: Refund identifier
• amount: Refunded value
• status: Refund status

Key Rules

• Refund availability depends on transaction status and payment method
• Refund updates are asynchronous and sent via notification