Manual do Dev
InstitucionalBlogService DeskStatus Page

Devolução

beta scopes: events.read pix.cashout.create

Suggest Edits

Após uma transação cash-in (recebimento), o recebedor pode devolver ao pagador o total do valor recebido ou parte dele.

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 depois desse período, será preciso realizar um Pix cash-out convencional.

Etapas

Consulta de eventos

Ao iniciar o processo de devolução, é preciso ter em mãos o valor do campo depositTransactionId, gerado no evento referente ao Pix cash-in.

Para recuperar esse valor, utilize o endpoint de consulta de eventos.

Endpoint

Para consumo deste endpoint, preencha os seguintes campos obrigatórios no path da requisição:

  • x-correlation-id: informe um GUID v4, gerado randomicamente. A cada requisição, deve-se gerar um novo GUID v4;
  • branch: informe a agência da conta recebedora da qual se deseja obter o evento;
  • account: conta recebedora;
  • includeDetails: inclua esse campo com o valor "true" para obter o objeto data no corpo da resposta com os detalhes do evento.

🚧

Importante

No header da requisição é obrigatório informar o campo x-correlation-id com um Guid.

Opcionalmente, insira no path os seguintes campos:

  • page: indique o número da página que deseja visualizar;
  • pageSize: especifique a quantidade de eventos retornados por páginas (máximo de 100 itens);
  • beginDateTime: insira a data de início dos eventos que deseja consultar no formato AAAA-MM-DD. Utilize esse campo em conjunto com o endDateTime para filtrar eventos por um range de datas;
  • endDateTime: insira a data final dos eventos que deseja consultar (formato AAAA-MM-DD); 
--request GET  
--url 'https://api-mtls.sandbox.bankly.com.br/events?branch={{branchNumber}}&account={{accountNumber}}&page={{pageNumber}}&pageSize={{eventsPerPage}}&includeDetails={{true}}&beginDateTime={{AAAA-MM-DD}}&endDateTime={{AAAA-MM-DD}}&cardProxy={{cardProxyNumber}}'  \
--header 'Accept: application/json'  \
--header 'api-version: 1.0' \
--header 'x-correlation-id: {{correlationId}}' \

Retorno

O valor do campo depositTransactionId retornado nessa requisição será utilizado para o preenchimento do campo authenticationCode no endpoint de devolução.

🚧

Importante

O campo depositTransactionId retornará apenas nos eventos cujo campo name seja igual a "PIX_CASH_IN_ACCOUNT".

{
   "aggregateId": "PIX_TRANSACTION_ID_96000a91-75aa-4989-935f-e94de7608fe4",
   "type": "TRANSACTION",
   "category": "EletronicTransfers",
   "documentNumber": "36436846816",
   "bankBranch": "0001",
   "bankAccount": "219568",
   "amount": 1,
   "index": "cash-in",
   "name": "PIX_CASH_IN_ACCOUNT",
   "timestamp": "2021-10-25T14:36:00+00:00",
   "data": {
      "TotalRefundedAmount": 1,
      "DepositTransactionId": "96000a91-75aa-4989-935f-e94de7608fe4",
      "ControlNumber": null,
      "TransactionAmount": 1,
      "ClearingAmount": 1,
      "OverLimitAmount": 0,
      "AddressKey": null,
      "Description": "DESCRIÇÃO",
      "Channel": "INTERNAL_SPI",
      "EndToEndId": null,
      "PixTransactionId": "00000000-0000-0000-0000-000000000000",
      "SenderAccount": {
         "Agency": "0001",
         "Account": "187470",
         "Document": "12345678902",
         "IspbNumber": "13140088",
         "Name": "Peter Parker"
      },
      "RecipientAccount": {
         "Agency": "0001",
         "Account": "219568",
         "Document": "12345678900",
         "IspbNumber": "13140088",
         "Name": "Carol Denvers"
      },
      "IsPixDeposit": true,
      "CorrelationId": null,
      "Document": "36436846816",
      "CompanyKey": "SDB2_BANKLYDELIVERY",
      "EventDateTime": "2021-10-25T14:36:00.039+00:00"
   },
   "status": "ACTIVE"
}

Requisição de devolução

Após realizar a consulta de eventos, você estará apto a fazer a requisição no nosso serviço de devolução.

Endpoint

Para consumo do endpoint de devolução, preencha os seguintes campos obrigatórios:

  • x-correlation-id: informe um GUID v4, gerado randomicamente. A cada requisição, deve-se gerar um novo GUID v4;
  • account: dados da conta que recebeu a transação original;
    • branch: número da agência;
    • number: número da conta;
    • type: informe o tipo de conta. "CHECKING" para conta-corrente, "SALARY" para conta-salário, "SAVINGS" para conta-poupança e "PAYMENT" para conta de pagamento;
  • authenticationCode: informe o valor retornado no campo depositTransactionId do endpoint de consulta de eventos;
  • amount: 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. Importante: o valor máximo a ser devolvido obrigatoriamente é o valor total da transação recebida.
  • refundCode: os possíveis códigos sã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.

Opcionalmente, insira mais detalhes sobre o motivo da devolução nos campos refundReason e description. 

--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": "187470", 
        "type": "PAYMENT" 
    }, 
    "authenticationCode": "79bb6e53-6869-42c6-be15-2dba237f306b", 
    "amount": 30, 
    "refundCode": "MD06", 
    "refundReason": "1", 
    "description": "{{refundDescription}}" 
}'

Retorno

O sucesso retornará o status code 202, e o “status” do retorno será CREATED. 

{
   "authenticationCode": "689b1722-2992-48ee-b904-ac774c27089b",
   "amount": 1,
   "description": "1",
   "correlationId": "6923bd23-3e80-485c-8edb-d1784930f834",
   "sender": {
      "documentType": "CPF",
      "account": {
         "branch": "0001",
         "number": "219568",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "13140088",
         "compe": "332",
         "name": "Acesso Soluções De Pagamento S.A."
      },
      "documentNumber": "12345678900",
      "name": "Carol Denvers"
   },
   "recipient": {
      "documentType": "CPF",
      "account": {
         "branch": "0001",
         "number": "187470",
         "type": "CHECKING"
      },
      "bank": {
         "ispb": "13140088",
         "compe": "332",
         "name": "Acesso Soluções De Pagamento S.A."
      },
      "documentNumber": "12345678902",
      "name": "Peter Parker"
   },
   "status": "CREATED",
   "createdAt": "2021-10-26T13:40:51.2434384Z",
   "updatedAt": "2021-10-26T13:40:51.4185601Z"
}

Erros

Status codeCódigoDescrição
422REFUND_TRANSFER_NOT_COMPLETEDEsse authenticationCode já foi utilizado em outra devolução.
422REFUND_TRANSFER_NOT_COMPLETEDA devolução ainda está em processamento.
422INVALID_PIX_CASH_IN_STATUSStatus de Pix cash-in inválido.
422INVALID_PIX_CASH_IN_TYPETipo de Pix cash-in inválido.
422INVALID_REFUND_PERIODPeríodo de devolução inválido.
422INVALID_PIX_CASH_INPix cash-in inválido.
422NOT_FOUND_PIX_TRANSFERTransferência Pix não encontrada.
422INVALID_AUTHENTICATION_CODEO authenticationCode é inválido.

Updated 11 months ago