Request cancellations and refunds
About this guide#
In this guide, we will describe the step-by-step process for canceling or refunding (fully or partially) your pending or paid orders through our e-commerce API.
Prerequisites#
Before starting your onboarding, you must have valid credentials. You can check how to obtain your credentials in this article.
How does it work?#
Authentication#
PicPay uses Bearer Token (JWT) authentication for API V2 requests. You should send the access token in the Authorization header.
Basic operation#
You can cancel or refund (fully or partially) any order generated by your e-commerce through the /payments/{referenceId}/refunds endpoint. Check the rules below:
Scenario 1 If the payment has already been made, the PicPay customer will be refunded provided that your Merchant account on PicPay has sufficient balance to cover the refund. If the PicPay customer received any cashback for this transaction, that amount will also be deducted from the customer (for this, the customer must have sufficient balance). All these requirements must be met for the transaction refund to be successful. In this case, the authorizationId (received in the paid order notification) must also be included in the request body.
Example of a full refund of a paid order:
In the example above, this order will change from the status paid to refunded.
Information
To perform a partial refund, also include the amount field in the request body, with the value to be refunded (always less than or equal to the total paid amount). As long as there is remaining paid balance, new partial refunds can be requested until the full amount has been refunded.
Scenario 2 If the payment has not yet been made, the transaction will be canceled on our server, preventing payment by the PicPay customer. In this case, authorizationId is not required, since there is no payment authorization for the order.
Example of cancellation of a pending order.
In the example above, this order will change from the status created to expired.
For transactions paid with balance, the amount will be returned to the user's wallet almost immediately after the operation. Refunding a transaction made with a credit card may take a few days to appear on the customer's statement.
Request response#
The summary field always returns the updated transaction values: authorized (authorized amount), paid (paid/captured amount) and refunded (already canceled/refunded amount).
Next steps#
Getting help#
We hope this article has been helpful! If you have any remaining questions, you can check our FAQ or contact us via email at negocios@atendimento.picpay.com.