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

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: {{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 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 YYYY-MM-DDTHH:mm:SS.MMMZ.
`updatedAt`	`string`	Data de atualização da transação, no formato YYYY-MM-DDTHH:mm:SS.MMMZ.

{
    "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.

Válido lembrar que a API também poderá retornar erros comuns entre todos os endpoints.

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.