Devolução de transferência Pix
stable
Após o recebimento de um valor via Pix (cash-in), o recebedor pode devolver ao pagador a quantia total recebida ou parte dela.
A devolução de um pagamento via Pix pode acontecer em até 90 dias após a data da transação original.
Caso o cliente queira fazer a devolução após esse período, será preciso realizar uma transferência via Pix (Pix cash-out) convencional.
Este endpoint permite realizar a devolução de valores recebidos via Pix.
Pré-requisito
Para que seja possível utilizar este endpoint, é necessário que:
- Possuir o código de autenticação do pagamento (authenticationCode) gerado no evento PIX_CASH_IN_WAS_RECEIVED.
Requisição
Requisição HTTP
POST 'https://api-mtls.sandbox.bankly.com.br/pix/cash-out:refund'
--location --request POST 'https://api-mtls.sandbox.bankly.com.br/pix/cash-out:refund' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-correlation-id: {{GUID}}' \
--header 'api-version: 1.0' \
--header 'Authorization: {{token}}' \
--data-raw '{
"account": {
"branch": "0001",
"number": "15164",
"type": "PAYMENT"
},
"authenticationCode": "79bb6e3-6869-42c6-be15-2dba237f306b",
"amount": 30,
"refundCode": "MD06",
"refundReason": "1",
"description": "{{refundDescription}}"
}'
Autorização
Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:
| Scope | Descrição |
|---|---|
pix.cashout.create | Concede acesso para iniciar um pagamento ou devolução via Pix. |
Cabeçalhos (Headers)
| Nome | Descrição |
|---|---|
api-version | Obrigatório. Versão da API. Atualmente estamos na versão 1.0. |
Authorization | Obrigatório. Token de autorização do tipo Bearer. |
x-correlation-id | Se desejar, informe um GUID v4, sendo um novo cada requisição. |
Parâmetros da rota (Path)
Não é necessário enviar parâmetros no path desta requisição.
Corpo da requisição (Body)
No body, envie os seguintes campos em formato JSON:
| Nome | Tipo | Descrição |
|---|---|---|
account | object | Obrigatório. Objeto que contém os dados da conta que recebeu a transação original. |
account.branch | string | Obrigatório. Número da agência. |
account.number | string | Obrigatório. Número da conta. |
account.type | string | Obrigatório. Tipo de conta, o qual pode ser CHECKING para conta corrente, SALARY para conta salário, SAVINGS para conta poupança e PAYMENT para conta de pagamento. |
authenticationCode | string | Obrigatório. Código de autenticação do pagamento. Informe o valor do campo authenticationCode gerado no evento PIX_CASH_IN_WAS_RECEIVED. |
amount | number | Obrigatório. Valor a ser devolvido. Pode ser o valor total da transação original que foi recuperado no evento disponível no extrato ou o valor parcial. |
refundCode | string | Obrigatório. Código da devolução. |
refundReason | string | Campo opcional que permite descrever o motivo da devolução. |
description | string | Campo opcional que permite adicionar uma descrição para a devolução. |
Importante
O valor máximo a ser devolvido obrigatoriamente é o valor total da transação recebida.
--location --request POST 'https://api-mtls.sandbox.bankly.com.br/pix/cash-out:refund' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-correlation-id: {{correlationId}}' \
--header 'api-version: 1.0' \
--header 'Authorization: {{token}}' \
--data-raw '{
"account": {
"branch": "0001",
"number": "15164",
"type": "PAYMENT"
},
"authenticationCode": "79bb6e3-6869-42c6-be15-2dba237f306b",
"amount": 30,
"refundCode": "MD06",
"refundReason": "1",
"description": "{{refundDescription}}"
}'
Código da devolução
| Código | Descrição |
|---|---|
| BE08 | Devolução de pagamento instantâneo devido a erro do PSP (Provedor de Serviços de Pagamento). Utilizado em caso de Mecanismo Especial de Devolução (MED). |
| FR01 | Devolução de pagamento motivada por fundada suspeita de fraude. Utilizado em caso de Mecanismo Especial de Devolução (MED). |
| MD06 | Devolução de pagamento instantâneo solicitada pelo usuário recebedor pagamento original. |
| SL02 | Devolução motivada por um erro relacionado ao saque Pix. |
Resposta (Response)
O status code 202 indicará que solicitação de devolução foi criada (status CREATED).
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
| Nome | Tipo | Descrição |
|---|---|---|
authenticationCode | string | Código de autenticação do pagamento. |
amount | number | Valor devolvido. |
description | string | Descrição da devolução. |
correlationId | string | GUID da requisição. |
sender | object | Objeto que contém os dados do pagador. |
sender.account | object | Objeto que contém os dados da conta do pagador. |
sender.account.branch | string | Número da agência. |
sender.account.number | string | Número da conta. |
sender.account.type | string | Tipo de conta, o qual pode ser CHECKING para conta corrente, SALARY para conta salário, SAVINGS para conta poupança e PAYMENT para conta de pagamento. |
sender.bank | object | Objeto com os dados do banco do pagador. |
sender.bank.ispb | string | ISPB do banco. |
sender.bank.compe | string | Código do banco. Esse campo não é retornado em caso de Pix externo. |
sender.bank.name | string | Nome do banco. Esse campo não é retornado em caso de Pix externo. |
sender.documentNumber | string | Número do documento do pagador. |
sender.documentType | string | Tipo de documento (CPF ou CNPJ). |
sender.name | string | Nome de registro conforme consta no cadastro da conta. Quando pessoa física, trata-se do nome de registro, e quando pessoa jurídica, trata-se da razão social da empresa. |
recipient | object | Objeto que contém os dados do recebedor. |
recipient.account | object | Objeto que contém informações sobre a conta do recebedor. |
recipient.account.branch | string | Número da agência. |
recipient.account.number | string | Número da conta. |
recipient.account.type | string | Tipo de conta, o qual pode ser CHECKING para conta corrente, SALARY para conta salário, SAVINGS para conta poupança e PAYMENT para conta de pagamento. |
recipient.bank | object | Objeto com os dados do banco recebedor. |
recipient.bank.ispb | string | ISPB da instituição recebedora do pagamento. |
recipient.bank.compe | string | Código do banco. |
recipient.bank.name | string | Nome do banco. |
recipient.documentNumber | string | Número do documento do recebedor (CPF ou CNPJ). |
recipient.documentType | string | Tipo de documento (CPF ou CNPJ). |
recipient.name | string | Nome do recebedor. Esse campo retornará o nome do documento de cadastro, e não o nome social. |
status | string | Situação da devolução. |
type | string | Tipo de transação, o qual pode ser CASH_OUT (pagamento/transferência) ou REFUND(devolução). |
createdAt | string | Data de criação da transação, no formato ISO 8601 - UTC. |
updatedAt | string | Data de atualização da transação, no formato ISO 8601 - UTC. |
{
"authenticationCode": "689b172-2992-48ee-b904-ac774c27089b",
"amount": 1,
"description": "1",
"correlationId": "693bd23-3e80-485c-8edb-d1784930f834",
"sender": {
"account": {
"branch": "0001",
"number": "540108",
"type": "CHECKING"
},
"bank": {
"ispb": "13140088",
"compe": "332",
"name": "Acesso Soluções De Pagamento S.A."
},
"documentNumber": "09992220074",
"documentType": "CPF",
"name": "Maria Quitéria de Jesus"
},
"recipient": {
"account": {
"branch": "0001",
"number": "15164",
"type": "CHECKING"
},
"bank": {
"ispb": "13140088",
"compe": "332",
"name": "Acesso Soluções De Pagamento S.A."
},
"documentNumber": "47742663023",
"documentType": "CPF",
"name": "Nísia Floresta"
},
"status": "CREATED",
"createdAt": "2021-10-26T13:40:51.2434384Z",
"updatedAt": "2021-10-26T13:40:51.4185601Z"
}
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.
Status da devolução
| Status | Descrição |
|---|---|
| CREATED | Transação criada, não finalizada. |
| IN_PROCESS | Transação em processo, não finalizada. |
| APPROVED | Transação aprovada, não finalizada. |
| REPROVED | Transação reprovada, não finalizada. |
| DONE | Transação concluída com sucesso. |
| UNDONE | A transação não pôde ser concluída. O valor foi estornado. |
| CANCELED | A transação foi cancelada. O saldo não foi afetado. |
Erros
Este endpoint pode retornar erros específicos, conforme a tabela a seguir:
| Status code | Código | Descrição |
|---|---|---|
| 422 | REFUND_TRANSFER_NOT_COMPLETED | Esse authenticationCode já foi utilizado em outra devolução. |
| 422 | REFUND_TRANSFER_NOT_COMPLETED | A devolução ainda está em processamento. |
| 422 | INVALID_PIX_CASH_IN_STATUS | Status de Pix cash-in inválido. |
| 422 | INVALID_PIX_CASH_IN_TYPE | Tipo de Pix cash-in inválido. |
| 422 | INVALID_REFUND_PERIOD | Período de devolução inválido. |
| 422 | INVALID_PIX_CASH_IN | Pix cash-in inválido. |
| 422 | NOT_FOUND_PIX_TRANSFER | Transferência Pix não encontrada. |
| 422 | INVALID_AUTHENTICATION_CODE | O authenticationCode é inválido. |
Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).
Eventos
Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:
| Nome do evento | Descrição |
|---|---|
PIX_REFUND_WAS_RECEIVED | O valor devolvido foi recebido no core bancário Bankly. |
Updated 12 days ago