Permite cancelar um pagamento de conta que ainda esteja elegível para cancelamento.

Esse endpoint deve ser utilizado quando for necessário impedir a execução de um pagamento previamente criado, desde que ele ainda não tenha sido processado.

Antes de realizar o cancelamento, recomenda-se consultar o pagamento e verificar a propriedade canBeCancelled do objeto bill.

Quando utilizar

Esse endpoint é recomendado em situações como:

• cancelamento solicitado pelo usuário;
• identificação de erro nos dados do pagamento;
• necessidade de impedir a liquidação antes do processamento;
• ajustes operacionais internos.

Caso o pagamento já tenha sido processado ou não esteja mais elegível para cancelamento, a operação poderá ser recusada.

Dependência com a consulta do pagamento

Antes de solicitar o cancelamento, recomenda-se consultar o pagamento e verificar o atributo:

{
  "canBeCancelled": true
}

Esse campo indica se o pagamento ainda pode ser cancelado.

📘

Importante

O fato de um pagamento existir não significa que ele ainda possa ser cancelado.

Sempre valide o atributo canBeCancelled antes de executar esta operação.

Fluxo recomendado

Em uma integração típica, o fluxo de cancelamento é:

Consultar pagamento
↓
Verificar canBeCancelled
↓
Executar o cancelamento
↓
Atualizar o status internamente

Comportamentos importantes

Ao cancelar um pagamento de conta:

• o pagamento não será realizado;
• o cancelamento não é reversível através deste endpoint;
• pagamentos já processados podem não permitir cancelamento;
• recomenda-se atualizar o status do pagamento no sistema de origem após a confirmação da operação.

⚠️

Importante

O cancelamento impede a execução do pagamento, mas não recria automaticamente uma nova solicitação.

Caso seja necessário realizar novamente o pagamento, uma nova operação deverá ser criada.

Exemplo de fluxo

Consultar o pagamento:

GET /v3/bill/{id}

Verificar:

{
  "canBeCancelled": true
}

Executar:

POST /v3/bill/{id}/cancel

Erros comuns

400 Bad Request

Pode ocorrer quando o pagamento não atende às condições necessárias para cancelamento.

401 Unauthorized

Indica falha na autenticação ou utilização de uma chave de API inválida.

404 Not Found

Indica que o identificador informado não corresponde a um pagamento existente.

Boas práticas

📘

Recomendado

• Consulte o pagamento antes de solicitar o cancelamento.
• Valide o atributo canBeCancelled.
• Atualize o status do pagamento no sistema de origem após a operação.
• Evite assumir que todo pagamento poderá ser cancelado.
• Trate respostas de erro para manter a consistência da integração.

Impactos operacionais

O cancelamento impede que o pagamento seja executado.

Caso a operação faça parte de processos financeiros, recomenda-se atualizar sistemas de conciliação, interfaces administrativas e notificações ao usuário para refletir corretamente o cancelamento realizado.

Conteúdos relacionados

• Consultar pagamento de conta.
• Criar pagamento de conta.
• Listar pagamentos de conta.
• Atualizar pagamento de conta.