6.1. Sending the request
Your POST must be sent to https://sandbox.pagbrasil.com/api/order/refund setting the content-type of the request header and body as "x-www-form-urlencoded".
Please note that this URL shall only be used for integration and testing procedures. Once the Payment Service Agreement is signed, you will receive the production environment's URL when you request your account to go live.
Request parameters:
Field | Description | Required | Length |
|---|---|---|---|
secret | Secret phrase as defined in the PagBrasil Dashboard | Yes | 128 |
pbtoken | Token assigned to your merchant account. | Yes | 32 |
order | Order number | Yes | 64 |
amount_refunded | Amount requested to be refunded (Brazilian Real) | Yes | 5.2 |
suspicious | Value "1" indicates that you are refunding the order because you suspect that it is a fraudulent order. That feeds our PagShield fraud prevention service database. Otherwise, set this parameter as "0" (or blank). | No | 1 |
customer_bank | Customer's bank number (número do banco). See note "b" | No | 3 |
customer_branch | Branch number (agência). | No | 12 |
customer_account | Account number (conta corrente). Must include the hyphen and the verification digit; for example: "12345678-0". | No | 12 |
Notes:
a) A successful response for the refund request will be "Refund request received".
b) Please find the bank numbers here (column "COD COMPENSAÇÃO").
6.2. Receiving the refund confirmation
You need to login to the PagBrasil Dashboard and specify the URL you want PagBrasil to notify you when the refund is processed.
PagBrasil's POST:
Field | Description | Length |
|---|---|---|
secret | Secret phrase as defined in the PagBrasil Dashboard | 128 |
payment_method | C = Credit card | 1 |
order | Order number | 64 |
amount_brl | Amount in Brazilian Real | 5.2 |
amount_refunded | Amount refunded (Brazilian Real) | 5.2 |
payment_status | C = Chargeback See note "a" | 1 |
signature | HMAC-MD5 hash that authenticates the IPN. See note "d" | 32 |
Notes:
a) The payment status is returned as "C" (Chargeback) when a previously authorized transaction is reversed by the credit card issuer. In addition our system will send a chargeback notification to the e-mail address you registered at the PagBrasil Dashboard.
b) The payment status is returned as "P" (Refund Processed) when the refund request was accepted by the credit card acquirer. The delay between the refund being accepted and the customer seeing the credit on their statement depends on the credit card issuer. If it is a refund via bank transfer, the status "P" indicates the refund request was submitted to the bank using the account information provided by the end customer. Please note that the Refund Processed status doesn't necessarily mean that the customer has received the credit, as the money can later be returned by the recipient's bank if the account information turns out to be incorrect.
c) The payment status is returned as "J" (Refund rejected) when the refund request was not accepted by the credit card acquirer. This usually happens when the order is older than 300 days. In this case our system will also send a notification to the email address you registered at the PagBrasil Dashboard, and you may refund the transaction through PagBrasil via bank transfer, by including the following parameters when requesting the refund via API:
customer_bank = Customer's bank number (número do banco). Please find the bank numbers here (column "COD COMPENSAÇÃO").
customer_branch = Branch number (agência).
customer_account = Account number (conta corrente). Must include the hyphen and the verification digit; for example: "12345-6".
The merchant needs to ask the end customer for their bank details and submit these to us using the parameters above.
The payment status will also returned as "J" when the money has been returned by the recipient's bank because the account information provided was incorrect. In this case, please ask the customer to confirm that the bank details are correct and that they are the account holder. When you have their correct information you may request the refund again.
When a refund was processed via bank transfer, one of the parameters returned when requesting information about a specific order is refund_info (see item 5.2), which includes the contents for parameters customer_bank, customer_branch and customer_account, formatted in a way your operator may easily review such information. Please see the following example.
Parameters sent when requesting a refund:
customer_bank = 001
customer_branch = 1234
customer_account = 12345678-0
Parameter refund_info returned when requesting information about this order:
Banco 001 - Agência 1234 - Conta 12345678-0
This way, your operator may copy/paste the information returned by refund_info when it's necessary to remind the customer what information was used to process the refund.
IMPORTANT: The bank account holder must be the customer, and not a third-party. The fee for this type of refund is the same as that applied for a boleto bancário refund. Please refer to your proposal or contract for further details.
d) To authenticate the legitimacy of the IPN, you may check the parameter secret and/or the parameter signature, which is a HMAC-MD5 hash based on three parameters and a key defined at the PagBrasil Dashboard, menu Account > Settings. The HMAC-MD5 source string is the concatenation of the values of the parameters order, amount_brl and payment_status and the total length for these three parameters. For example, if parameter order="1234567890", amount_brl="39.50" and payment_status="P", the parameter signature would be "3093a7dffa0c04e74e827d1b52ef514e".
In this example, the hash for the signature was computed using the string "123456789039.50P16" with the key "36d5f7184574caf84f5b48530ac0d690".