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} |
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": "OPERACAO REALIZADA COM SUCESSO",
"ReturnCode": "0",
"ReturnMessage": "OPERACAO REALIZADA 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. |