Passo-a-passo - Devolvendo uma cobrança paga
1. Primeiro passo: Possuir uma cobrança paga
Para realizar a devolução você precisa ter uma cobrança em um estado que permita a devolução, acima você encontra os status correspondentes para cada forma de pagamento passíveis dessa operação;
Ao gerar a cobrança você terá no retorno da requisição uma serie de informações entre eles o id (identificador PagSeguro) da cobrança além é claro de um link hypermedia destinado exclusivamente a essa operação com o id já montado na URL.
Veja um exemplo de resposta resumida abaixo contendo esses dois parâmetros:
{
"id": "CHAR_D32A01A9-92A6-4755-B21D-7B6A1291F7AD",
"status": "PAID",
...
"links": [
{
"rel": "CHARGE.CANCEL",
"href": "https://sandbox.api.pagseguro.com/charges/CHAR_D32A01A9-92A6-4755-B21D-7B6A1291F7AD/cancel",
"media": "application/json",
"type": "POST"
},
...
]
}
O exemplo de JSON acima foi editado para mostrar apenas os parâmetros necessários para o passo seguinte.
Referência API
2. Segundo passo: Devolvendo o valor pago
Com o id de cobrança ou o links[].href referenrte ao links[].rel = CHARGE.CANCEL em mão você poderá realizar a requisição de devolução da cobrança.
Essa etapa será uma requisição no recurso /charges/{id}/cancel onde o {id} se refere ao identificador PagSeguro da cobrança.
Você poderá realizar a devolução tanto em valor integral da cobrança quando um valor parcial, na requisição você sempre deve informar o valor ao qual você deseja devolver.
Devolução total
Veja exemplo abaixo de uma devolução total:
{
"amount": {
"value": 1000
}
}
{
"id": "CHAR_be4545a8-8e62-4d44-85fa-66ccaf2329af",
"reference_id": "e853052b-046c-4714-aa6b-f05f50af34a9",
"status": "CANCELED",
"created_at": "2019-08-21T15:14:58.121-03:00",
"paid_at": "2019-08-21T15:14:58.121-03:00",
"description": "Motivo da cobranca",
"amount": {
"value": 1000,
"currency": "BRL",
"summary": {
"total": 1000,
"paid": 1000,
"refunded": 1000
}
},
"payment_response": {
"code": "20000",
"message": "SUCESSO",
"reference": "1566411299393"
},
"payment_method": {
"type": "CREDIT_CARD",
"installments": 1,
"capture": true,
"card": {
"brand": "VISA",
"first_digits": "411111",
"last_digits": "1111",
"exp_month": "12",
"exp_year": "2026",
"holder": {
"name": "Jose da Silva"
}
}
},
"links": [],
"notification_urls": [
"https://api.runscope.com/radar/inbound/f9e7bcbd-50dc-4821-8959-9854796d01c3"
],
"metadata": {}
}
Devolução parcial
Veja exemplo abaixo de uma devolução parcial:
{
"amount": {
"value": 500
}
}
{
"id": "CHAR_be4545a8-8e62-4d44-85fa-66ccaf2329af",
"reference_id": "e853052b-046c-4714-aa6b-f05f50af34a9",
"status": "PAID",
"created_at": "2019-08-21T15:14:58.121-03:00",
"paid_at": "2019-08-21T15:14:58.121-03:00",
"description": "Motivo da cobranca",
"amount": {
"value": 1000,
"currency": "BRL",
"summary": {
"total": 1000,
"paid": 1000,
"refunded": 500
}
},
"payment_response": {
"code": "20000",
"message": "SUCESSO",
"reference": "1566411299393"
},
"payment_method": {
"type": "CREDIT_CARD",
"installments": 1,
"capture": true,
"card": {
"brand": "VISA",
"first_digits": "411111",
"last_digits": "1111",
"exp_month": "12",
"exp_year": "2026",
"holder": {
"name": "Jose da Silva"
}
}
},
"links": [],
"notification_urls": [
"https://api.runscope.com/radar/inbound/f9e7bcbd-50dc-4821-8959-9854796d01c3"
],
"metadata": {}
}
Devolução parcial não muda status da cobrança
Atenção quando você realizar uma devolução do valor parcial da cobrança o status não será alterado, ele permanecera com status de Pago (
PAID).Utilize o parâmetro
amount.summary.refundedpara confirmar o valor que foi devolvido ao comprador.
3. Terceiro passo: Tratar a resposta de cobrança
Nessa segunda etapa você deve tratar o retorno da API de devolução e dar um feedback amigável ao seu cliente, seja positivo ou negativo.
Para os casos de feedback positivo você pode:
- Confirmar ao cliente todo o valor já devolvido com base no parâmetro
amount.summary.refunded.
Para os casos de feedback negativo você pode:
- Informar que você fará novas tentativas de devolução conforme disponibilidade do recurso.
Referência API