Devolução de transferência Pix

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 (Request)

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/pix/cash-out:refund

--request POST \
--url '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}}" 
}'

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`	Obrigatório. Informe um GUID, 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 deverá conter informações sobre a 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, que pode ser "CHECKING" (conta corrente), "SALARY" (conta salário), "SAVINGS" (poupança) e "PAYMENT" (conta de pagamento).
`authenticationCode`	`string`	Obrigatório. Identificador único da transação. 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`	Motivo da devolução.
`description`	`string`	Descrição da devolução.

🚧
Importante
O valor máximo a ser devolvido obrigatoriamente é o valor total da transação recebida.

{ 
    "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.
FR01	Devolução de pagamento motivada por fundada suspeita de fraude.
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`	Identificador único da transação, no formato GUID v4.
`amount`	`number`	Valor da transação.
`description`	`string`	Descrição da devolução.
`correlationId`	`string`	GUID informado em cada requisição realizada no endpoint.
`sender`	`object`	Objeto que contém informações sobre o pagador da transação.
`sender.account`	`object`	Objeto que contém informações sobre a conta do pagador da transação.
`sender.account.branch`	`string`	Número da agência.
`sender.account.number`	`string`	Número da conta.
`sender.account.type`	`string`	Tipo de conta, que pode ser "CHECKING" (conta corrente), "SALARY" (conta salário), "SAVINGS" (poupança) e "PAYMENT" (conta de pagamento).
`sender.bank`	`object`	Objeto que contém informações sobre o banco pagador da transação.
`sender.bank.ispb`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco pagador da transação.
`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.
`sender.documentType`	`string`	Tipo de documento do pagador da transação, que pode ser "CPF" ou "CNPJ".
`sender.name`	`string`	Nome de registro do pagador da transação, 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 informações sobre o recebedor da transação.
`recipient.account`	`object`	Objeto que contém informações sobre a conta do recebedor da transação.
`recipient.account.branch`	`string`	Número da agência.
`recipient.account.number`	`string`	Número da conta.
`recipient.account.type`	`string`	Tipo de conta, que pode ser "CHECKING" (conta corrente), "SALARY" (conta salário), "SAVINGS" (poupança) e "PAYMENT" (conta de pagamento).
`recipient.bank`	`object`	Objeto que contém informações sobre o banco do recebedor da transação.
`recipient.bank.ispb`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco recebedor da transação.
`recipient.bank.compe`	`string`	Código do banco.
`recipient.bank.name`	`string`	Nome do banco.
`recipient.documentNumber`	`string`	Número do documento.
`recipient.name`	`string`	Nome do recebedor da transação. 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, que 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	Mensagem	Descrição
422	REFUND_TRANSFER_NOT_COMPLETED	Refund already made with this authentication code	Esse `authenticationCode` já foi utilizado em outra devolução.
422	REFUND_TRANSFER_NOT_COMPLETED	Refund already in processing	A devolução ainda está em processamento.
422	INVALID_PIX_CASH_IN_STATUS	Invalid pix cash-in status	Status de Pix cash-in inválido.
422	INVALID_PIX_CASH_IN_TYPE	Invalid pix cash-in type	Tipo de Pix cash-in inválido.
422	INVALID_REFUND_PERIOD	Invalid refund period	Período de devolução inválido.
422	INVALID_PIX_CASH_IN	Invalid pix cash-in	Pix cash-in inválido.
422	NOT_FOUND_PIX_TRANSFER	Not found pix transfer	Transferência Pix não encontrada.
422	INVALID_AUTHENTICATION_CODE	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.

Devolução de transferência Pix

Pré-requisito

Requisição (Request)

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

🚧
Importante

Código da devolução

Resposta (Response)

👍
Dica

Status da devolução

Erros

Eventos

Pré-requisito

Requisição (Request)

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

🚧Importante

Código da devolução

Resposta (Response)

👍Dica

Status da devolução

Erros

Eventos

🚧
Importante

👍
Dica