Refund API

Refund API is used to request a refund, according to the flow below:

Work Flow

How it Works

  1. Merchant requests refund to PagSeguro
  2. PagSeguro receives the data and returns the refund identifier to the Merchant
  3. PagSeguro processes the data transferred by the Merchant
  4. PagSeguro notifies the Merchant with the status of the transaction change
  5. Merchant receives notification and updates order status as described in the Notify API topic

To identify whether the transaction is refundable, you can check through the query, the “refundable” parameter indicates whether the payment can be refunded. The other way is to validate which methods are refundable by PagSeguro, check the list of payment methods available by country.

📘

Refund API URL for Production

https://api.international.pagseguro.com/v3/transactions/{transaction_code}/refunds

Method: POST

🚧

Refund API URL for Sandbox

https://api.sandbox.international.pagseguro.com/v3/transactions/{transaction_code}/refunds

Method: POST

Request

  • To perform authentication, use the default authentication method defined in Authentication Section.
  • Use Content-Type header with the value "application/json".

Query parameter list:

ParametersDescriptionTypeValidationErrorsMandatory
transaction_codeTransaction code UUID, uppercase formatted with hyphens/dashesString--Yes

Body parameter list:

ParametersDescriptionTypeValidationErrorsMandatory
notification_urlURL (must bind ports 80 or 443) used to send transaction status change notifications by HTTPStringA Valid URL, Max. 200[*]Yes
amountAmount to be refunded. If not sent, the refund will be processed for the entire value of the transactionFloatMin. 0.01, Max. transaction amount[*]No. Default: transaction amount
referenceMerchant referenceStringMax. 50[*]No

Example

To refund a transaction, make a POST request as an example.

Example URL:


https://api.international.pagseguro.com/v3/transactions/00EEE57E-2DCA-4580-A33C-76D9773C9808/refunds


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

Response

ParametersDescriptionTypeDetailsDetails
idRefund identifierStringString-
referenceMerchant referenceStringString-
amountAmount to be refundedFloatFloat-
statusRefund statusStringString[*]
created_atRefund creation date in Coordinated Universal Time (UTC)UTC DateTimeUTC DateTime-
updated_atRefund last update date in Coordinated Universal Time (UTC)UTC DateTimeUTC DateTime-

Example

Status 201 Created

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

Refund Status

Refund status returned by PagSeguro:

NameDescription
REQUESTEDRefund requested by Customer.
PROCESSINGRefund in process.
PROCESSEDRefund successfully completed.
REJECTEDRefund was rejected.