Cancellation Reasons
When a payout is rejected (webhook status 2), the payload includes two fields that explain why:
cancel_reason— a normalized, machine-readable code. Match your handling logic on this field.cancel_details— a human-readable explanation (in Portuguese), useful for logs and support.
tip
Always branch on cancel_reason, never on cancel_details. The detail text is human-readable and may change, so don't rely on it for programmatic logic.
Cancellation codes
cancel_reason | cancel_details | Description | Pix / SPI code |
|---|---|---|---|
SETTLEMENT_TIMEOUT | Liquidação interrompida por tempo limite. | Settlement was aborted because it exceeded the time limit. | AB03 |
CREDITOR_AGENT_ERROR | Transação interrompida devido a erro no PSP do recebedor. | The transaction was stopped due to an error at the beneficiary's payment service provider (PSP). | AB09 |
DEBTOR_AGENT_TIMEOUT | Transação interrompida por tempo limite no PSP do pagador. | The transaction timed out at the payer's payment service provider (PSP). | AB11 |
INVALID_CREDITOR_ACCOUNT | Conta do recebedor inválida ou ausente. | The beneficiary account is invalid or missing. | AC03 |
ACCOUNT_BLOCKED | Conta bloqueada para movimentações. | The account is blocked and cannot receive transactions. | AC06 |
CREDITOR_ACCOUNT_CLOSED | Conta do recebedor encerrada. | The beneficiary account has been closed. | AC07 |
INVALID_CREDITOR_ACCOUNT_TYPE | Tipo da conta do recebedor inválido ou ausente. | The beneficiary account type is invalid or missing. | AC14 |
TRANSACTION_NOT_SUPPORTED | Tipo de transação não suportado ou não autorizado para esta conta. | This transaction type is not supported or not authorized for the account. | AG03 |
SAME_INSTITUTION_TRANSFER_NOT_ALLOWED | Transferências entre contas da mesma instituição não são permitidas. | Transfers between accounts at the same institution are not allowed. | AG12 |
RETURN_OF_RETURNED_PAYMENT_NOT_ALLOWED | Não é permitida a devolução de um pagamento que já foi devolvido. | A payment that has already been returned cannot be returned again. | AG13 |
INCORRECT_AGENT | Participante incorreto no fluxo do pagamento. | An incorrect participant (PSP) was used in the payment flow. | AGNT |
ZERO_AMOUNT | Valor da transação igual a zero. | The transaction amount is zero. | AM01 |
AMOUNT_EXCEEDS_MAXIMUM | Valor da transação acima do máximo permitido. | The transaction amount is above the maximum allowed. | AM02 |
INSUFFICIENT_BALANCE | Saldo insuficiente. | Insufficient balance to complete the transaction. | AM04 |
UNEXPECTED_AMOUNT | Valor recebido diferente do valor esperado. | The received amount differs from the expected amount. | AM09 |
INVALID_AMOUNT | Valor da transação inválido ou ausente. | The transaction amount is invalid or missing. | AM12 |
INVALID_TRANSACTION_COUNT | Quantidade de transações inválida ou ausente. | The number of transactions is invalid or missing. | AM18 |
SETTLEMENT_LIMIT_EXCEEDED | Valor da transação excede o limite de liquidação. | The transaction amount exceeds the settlement limit. | AM23 |
CREDITOR_ACCOUNT_MISMATCH | Identificação do recebedor incompatível com a conta informada. | The beneficiary's identification does not match the account provided. | BE01 |
UNRECOGNIZED_INITIATING_PARTY | Parte que iniciou o pagamento não reconhecida pelo cliente final. | The party that initiated the payment was not recognized by the end customer. | BE05 |
INVALID_IDENTIFICATION | Identificação inválida ou ausente. | The identification provided is invalid or missing. | BE15 |
INVALID_CREDITOR_IDENTIFICATION | Identificação do recebedor inválida ou ausente. | The beneficiary's identification is invalid or missing. | BE17 |
INVALID_CREDITOR_IDENTIFIER | Identificador do recebedor inválido. | The beneficiary identifier is invalid. | CH11 |
INVALID_CONTENT | Conteúdo da mensagem inválido. | The message content is invalid. | CH16 |
AUTHORIZATION_CANCELLED | Autorização cancelada. | The authorization was cancelled. | CN01 |
PAYMENT_REJECTED_BY_BANK | Pagamento rejeitado pela instituição devido ao conteúdo da transação. | The payment was rejected by the institution due to the transaction content. | DS04 |
SIGNER_NOT_AUTHORIZED_FOR_OPERATION | Signatário não autorizado a executar este tipo de operação. | The signer is not authorized to perform this type of operation. | DS0G |
USER_NOT_ACTIVATED | Usuário ainda não ativado. | The user has not been activated yet. | DS27 |
INVALID_CREATION_DATETIME | Data ou hora de criação da mensagem inválida. | The message creation date or time is invalid. | DT02 |
PROCESSING_CUTOFF_EXCEEDED | Transação recebida após a data-limite de processamento. | The transaction was received after the processing cut-off. | DT05 |
DUPLICATE_PAYMENT | Pagamento duplicado. | Duplicate payment. | DUPL |
SETTLEMENT_FAILED | Falha na liquidação da transação. | Settlement of the transaction failed. | ED05 |
INVALID_PURPOSE | Finalidade do pagamento inválida ou ausente. | The payment purpose is invalid or missing. | FF07 |
INVALID_END_TO_END_ID | Identificador EndToEnd inválido ou ausente. | The EndToEnd identifier is invalid or missing. | FF08 |
FRAUDULENT_ORIGIN | Transação originada de forma fraudulenta. | The transaction originated fraudulently. | FRAD |
INVALID_FIELD_DETAILS | Detalhes inválidos para o campo informado. | Invalid details for the field provided. | INDT |
MANDATE_NOT_FOUND | Autorização ou mandato inexistente. | The authorization or mandate does not exist. | MD01 |
INVALID_DEBTOR_AGENT_IDENTIFIER | Identificador do participante do pagador inválido ou ausente. | The payer's participant (PSP) identifier is invalid or missing. | RC09 |
INVALID_CREDITOR_AGENT_IDENTIFIER | Identificador do participante do recebedor inválido ou ausente. | The beneficiary's participant (PSP) identifier is invalid or missing. | RC10 |
REGULATORY_REASON | Transação rejeitada por motivo regulatório. | The transaction was rejected for a regulatory reason. | RR04 |
INVALID_TAX_INFORMATION | Informações tributárias inválidas ou ausentes. | Tax information is invalid or missing. | RR06 |
CREDITOR_AGENT_SERVICE_RESTRICTION | Transação rejeitada devido a restrição de serviço do PSP do recebedor. | The transaction was rejected due to a service restriction at the beneficiary's PSP. | SL02 |
UNJUSTIFIED_PAYMENT | Pagamento não justificado. | Unjustified payment. | UPAY |
DICT_KEY_NOT_FOUND | Chave Pix não encontrada. | The Pix key was not found in the DICT directory. | — |