Request a Pix refund

ℹ️
Learn more about this feature in the documentation.

If you need to return a Pix transfer, you can perform an operation called a refund. When a refund is accepted, a notification will be sent to your store.

The shopper must request the merchant to refund all or part of a payment made, through an appropriate communication channel;
The merchant agrees and identifies the original payment made via Pix.

When can I request a Pix refund?

You can request a Pix refund, for example, in cases of product return, billing error, or product unavailability in stock.

Who requests the Pix refund via the Cielo E-commerce API?

The merchant (seller who received the Pix transaction) is responsible for requesting the refund from the Cielo E-commerce API, either on their own or at the shopper's request. Pay attention to the deadlines (according to Banco Central regulations).

How to request a Pix refund?

Via Cielo E-commerce API, Cielo Gestão App, or Cielo website.

Pix Refund Rules

The refund will only occur if there is a balance in the merchant's payment account. To have a balance, you must choose Free Movement Management for your Pix account;
The Pix transaction fee and/or creation fee amounts will not be refunded;
For transfers, sales, and other Pix transactions, the cancellation period is up to 90 days from the date of the original transaction, as specified by Banco Central;
A Pix refund can be full (total transaction amount) or partial (part of the transaction amount).

⚠️
Attention
Merchants who opt for automatic transfer from the Pix account (Simplified Management) will not have a balance in the payment account. Therefore, it will not be possible to successfully process the refund, and the response will be “Merchant with insufficient balance for refund”.

Request

Environment	Method	Endpoint
Sandbox	put	`https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void?amount={Amount}`
Production	put	`https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void?amount={Amount}`

⚠️
Partial refund
To perform a partial refund, you must include the Amount parameter in the path. This parameter defines the amount to be refunded, in cents (e.g., R$1.00 = 100).
For a partial refund, the endpoint will be:

Sandbox: https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void?amount={Amount}

Production: https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void?amount={Amount}

If the Amount parameter is not provided, the refund will be considered as total.

Path parameters

Field	Type	Description
`PaymentId`	string	Payment identification number, returned by the API when creating the Pix QR Code. Size: 36.

Header Parameters

Property	Description	Type	Size	Required
`MerchantId`	Merchant identifier in the Cielo E-commerce API.	GUID	36	Yes
`MerchantKey`	Public key for dual authentication in the Cielo E-commerce API.	string	40	Yes
`RequestId`	Request identifier, used when the merchant uses different servers for each GET/POST/PUT.	GUID	36	No

Response

{
        "Status": 2,
        "ReasonCode": 8,
        "ReasonMessage": "Scheduled",
        "ProviderReturnCode": "0",
        "ProviderReturnMessage": "Devolução solicitada com sucesso",
        "ReturnCode": "0",
        "ReturnMessage": "Devolução solicitada com sucesso",
        "AuthorizationCode": "E01027058202412021928yOpJfcc9zLl",
        "Links": [
                {
                        "Method": "GET",
                        "Rel": "self",
                        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/b8c1b2ea-e06a-4135-9389-8bdbdccacd20"
                },
                {
                        "Method": "PUT",
                        "Rel": "void",
                        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/b8c1b2ea-e06a-4135-9389-8bdbdccacd20/void"
                }
        ]
}

The following table presents the main parameters that can be returned by the API when refunding a Pix:

Field	Type	Description
`Status`	number	Transaction status.
`ReasonCode`	number	Return code.
`ReasonMessage`	number	Return message.
`ProviderReturnCode`	number	Provider return code.
`ProviderReturnMessage`	string	Provider return message.
`AuthorizationCode`	string	Corresponds to the Pix transaction `EndToEndId`.

Field updates

See the changes in the fields returned in the query when updating the Cielo provider to Cielo2:

Fields	Previous integration	New integration (Cielo2)
`Tid`	Represented the QR Code ID.	No longer exists.
`ProofOfSale`	Represented the Pix NSU.	No longer exists.
`AuthorizationCode`	Did not exist.	Represents the Pix transaction `EndToEndId`.