Cancelamento

stable

Este endpoint permite que o parceiro realize o cancelamento de um boleto a qualquer momento após seu registro, desde que ele não tenha sido pago.

O cancelamento de um boleto pode ocorrer por duas razões:

  • Solicitação do beneficiário final;
  • Decurso do prazo de pagamento. Nesse caso o boleto será cancelado automaticamente para garantir que não haverá pagamento.

O cancelamento por decurso de prazo de pagamento considerará, por padrão, a data de vencimento do boleto (dueDate).

Porém, caso o título sofra a incidência de juros e/ou multa, o cancelamento ocorrerá somente após a nova data de vencimento do documento (informada no campo closePayment).

🚧

Importante

O cancelamento do boleto por decurso de prazo ocorre em até 2 dias úteis.

Pré-requisitos

Para que seja possível utilizar este endpoint, é necessário que:

  • O boleto tenha sido registrado;
  • O boleto não tenha sido pago.

Requisição

Requisição HTTP

DELETE https://api-mtls.sandbox.bankly.com.br/bankslip/cancel
--location --request DELETE ' https://api-mtls.sandbox.bankly.com.br/bankslip/cancel' \  
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'api-version: 2.0' \  
--header 'Authorization: Bearer {{Token}} ' 
--data-raw '{ 
     “authenticationCode”: "5566165e-51fb-459b-a31c-1e996165280b", 
     "account": { 
        "number": "00001", 
        "branch": "15164" 
        }     
    }'

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
boleto.deleteConcede acesso para realizar o cancelamento de boletos.

Cabeçalhos (Headers)

NomeDescrição
api-versionObrigatório. Versão da API, que, neste caso, é 2.0.
authorizationObrigatório. Token de autorização do tipo Bearer.

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
authenticationCodestringObrigatório. Identificador único do boleto.
accountobjectObrigatório. Objeto que contém informações sobre a conta do beneficiário final do boleto.
account.branchstringObrigatório. Número da agência bancária.
account.numberstringObrigatório. Número da conta.
{ 
     "authenticationCode": "5566165e-51fb-459b-a31c-1e996165280b", 
     "account": { 
        "number": "00001", 
        "branch": "15164" 
        }     
 }

Resposta (Response)

status code 200 indicará que o boleto foi cancelado com sucesso.

👍

Dica

Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

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

Status codeCódigoMensagemDescrição
400BANKSLIP_INVALID_STATUS_OPERATIONInvalid bankslip status to perform this operationO boleto está com status diferente de “Registered”.
400BANKSLIP_INVALID_EXPIRATION_DATEIt is not possible to cancel bankslip after the DueDate or ClosePaymentO boleto não pode ser cancelado após a data de vencimento (dueDate) ou após a data limite de pagamento (closePayment).

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.

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. O evento é:

EventoDescrição
BOLETO_WAS_CANCELLED_BY_RECIPIENTO boleto foi cancelado pelo recebedor do pagamento.