Manual do Dev
InstitucionalBlogService DeskStatus Page

Devolução de transferência Pix

Suggest Edits

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:

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:

ScopeDescrição
pix.cashout.createConcede acesso para iniciar um pagamento ou devolução via Pix.

Cabeçalhos (Headers)

NomeDescrição
api-versionObrigatório. Versão da API. Atualmente estamos na versão 1.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.
x-correlation-idObrigató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:

NomeTipoDescrição
accountobjectObrigatório. Objeto que deverá conter informações sobre a conta que recebeu a transação original.
account.branchstringObrigatório. Número da agência.
account.numberstringObrigatório. Número da conta.
account.typestringObrigatório. Tipo de conta, que pode ser "CHECKING" (conta corrente), "SALARY" (conta salário), "SAVINGS" (poupança) e "PAYMENT" (conta de pagamento).
authenticationCodestringObrigatório. Identificador único da transação. Informe o valor do campo authenticationCode gerado no evento PIX_CASH_IN_WAS_RECEIVED.
amountnumberObrigató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.
refundCodestringObrigatório. Código da devolução.
refundReasonstringCampo opcional que permite descrever o motivo da devolução.
descriptionstringCampo 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.

{ 
    "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ódigoDescrição
BE08Devolução de pagamento instantâneo devido a erro do PSP.
FR01Devolução de pagamento motivada por fundada suspeita de fraude.
MD06Devolução de pagamento instantâneo solicitada pelo usuário recebedor pagamento original.
SL02Devoluçã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:

NomeTipoDescrição
authenticationCodestringIdentificador único da transação, no formato GUID v4.
amountnumberValor da transação.
descriptionstringCampo opcional que permite adicionar uma descrição para a devolução.
correlationIdstringGUID informado em cada requisição realizada no endpoint.
senderobjectObjeto que contém informações sobre o pagador da transação.
sender.accountobjectObjeto que contém informações sobre a conta do pagador da transação.
sender.account.branchstringNúmero da agência.
sender.account.numberstringNúmero da conta.
sender.account.typestringTipo de conta, que pode ser "CHECKING" (conta corrente), "SALARY" (conta salário), "SAVINGS" (poupança) e "PAYMENT" (conta de pagamento).
sender.bankobjectObjeto que contém informações sobre o banco pagador da transação.
sender.bank.ispbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco pagador da transação.
sender.bank.compestringCódigo do banco. Esse campo não é retornado em caso de Pix externo.
sender.bank.namestringNome do banco. Esse campo não é retornado em caso de Pix externo.
sender.documentNumberstringNúmero do documento.
sender.documentTypestringTipo de documento do pagador da transação, que pode ser "CPF" ou "CNPJ".
sender.namestringNome 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.
recipientobjectObjeto que contém informações sobre o recebedor da transação.
recipient.accountobjectObjeto que contém informações sobre a conta do recebedor da transação.
recipient.account.branchstringNúmero da agência.
recipient.account.numberstringNúmero da conta.
recipient.account.typestringTipo de conta, que pode ser "CHECKING" (conta corrente), "SALARY" (conta salário), "SAVINGS" (poupança) e "PAYMENT" (conta de pagamento).
recipient.bankobjectObjeto que contém informações sobre o banco do recebedor da transação.
recipient.bank.ispbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco recebedor da transação.
recipient.bank.compestringCódigo do banco.
recipient.bank.namestringNome do banco.
recipient.documentNumberstringNúmero do documento.
recipient.namestringNome do recebedor da transação. Esse campo retornará o nome do documento de cadastro, e não o nome social.
statusstringSituação da devolução.
typestringTipo de transação, que pode ser "CASH_OUT" (pagamento/transferência) ou "REFUND" (devolução).
createdAtstringData de criação da transação, no formato ISO 8601 - UTC.
updatedAtstringData 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

StatusDescrição
CREATEDTransação criada, não finalizada.
IN_PROCESSTransação em processo, não finalizada.
APPROVEDTransação aprovada, não finalizada.
REPROVEDTransação reprovada, não finalizada.
DONETransação concluída com sucesso.
UNDONEA transação não pôde ser concluída. O valor foi estornado.
CANCELEDA transação foi cancelada. O saldo não foi afetado.

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status codeCódigoMensagemDescrição
422REFUND_TRANSFER_NOT_COMPLETEDRefund already made with this authentication codeEsse authenticationCode já foi utilizado em outra devolução.
422REFUND_TRANSFER_NOT_COMPLETEDRefund already in processingA devolução ainda está em processamento.
422INVALID_PIX_CASH_IN_STATUSInvalid pix cash-in statusStatus de Pix cash-in inválido.
422INVALID_PIX_CASH_IN_TYPEInvalid pix cash-in typeTipo de Pix cash-in inválido.
422INVALID_REFUND_PERIODInvalid refund periodPeríodo de devolução inválido.
422INVALID_PIX_CASH_INInvalid pix cash-inPix cash-in inválido.
422NOT_FOUND_PIX_TRANSFERNot found pix transferTransferência Pix não encontrada.
422INVALID_AUTHENTICATION_CODEInvalid authentication codeO 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 eventoDescrição
PIX_REFUND_WAS_RECEIVEDO valor devolvido foi recebido no core bancário Bankly.

Updated 7 days ago

Copyright © 2021 Acesso Soluções de Pagamento S.A - Todos os direitos reservados