Mensagens de Cancelamento (cancellationReason)

Lista de todas as mensagens possíveis no campo cancellationReason de uma transação.

Formato de resposta da API

Os erros chegam ao integrador em dois formatos distintos, dependendo de quando ocorrem.

Erro síncrono — resposta HTTP direta

Retornado imediatamente na requisição quando o erro é detectado antes de chegar ao provedor (ex.: saldo insuficiente, permissão negada, formato de chave PIX inválido, valor fora dos limites).

{
  "statusCode": 422,
  "message": "Saldo insuficiente para realizar a transação",
  "error": "Unprocessable Entity"
}

Erro assíncrono — transação cancelada

Ocorre quando o provedor rejeita a operação após a transação já ter sido criada. A requisição original retorna 200 normalmente; o erro é identificado ao consultar a transação.

{
  "id": "txn_abc123",
  "status": "CANCELED",
  "cancellationReason": "Chave Pix informada inválida",
  ...
}

Recomendação de integração: monitore o campo status via webhook ou polling. Quando status === "CANCELED", exiba cancellationReason ao usuário final.

Mensagens de cancelamento