Documentação
Status de transações e saques
Toda transação (cash-in) e todo saque (cash-out) tem um campo status que representa em que ponto do ciclo de vida ele está. Use esta referência para saber o que cada valor significa e qual evento de webhook ele dispara.
💡 Os status abaixo são os valores exatos que chegam no campo
statusda API (formato V1) e que você pode usar para filtrar. No Payload v2, o mesmo evento vira um nome dotado (ex.:APPROVED→cashin.paid).
Status de transação (cash-in)
| Status | Significado | Final? | Evento webhook |
|---|---|---|---|
PENDING | Cobrança criada, aguardando pagamento (PIX não pago ou cartão não capturado). | Não | — |
APPROVED | Pagamento confirmado e valor creditado no seu saldo. | ✅ | cashin.paid |
REJECTED | Recusada pelo PSP/emissor (ex.: cartão negado). Nenhum crédito é gerado. | ✅ | — |
CANCELED | Cancelada antes do pagamento (expiração do PIX ou cancelamento). | ✅ | — |
REFUNDED | Estornada com sucesso — o valor voltou ao pagador. | ✅ | cashin.refunded |
REFUNDED_PROCESSING | Estorno solicitado e em processamento (ainda não concluído). | Não | — |
CHARGEBACK | Contestação de cartão (chargeback) aberta pelo portador. | Não | infraction.updated |
BLOCKED | Saldo retido por MED / disputa de compliance (Pix). | Não | infraction.updated |
INCOSISTENT | Valor pago ≠ valor cobrado. Anomalia — não entregue nem estorne automaticamente; abra um ticket com o transaction_id. | Não | cashin.paid (com status embutido) |
ERROR | Falha técnica durante o processamento. | ✅ | — |
Status de saque (cash-out)
| Status | Significado | Final? | Evento webhook |
|---|---|---|---|
WITHDRAW_INFORMATION | Registro informativo/interno anterior à solicitação. | Não | — |
WITHDRAW_REQUEST | Saque solicitado e na fila para processamento. | Não | — |
WITHDRAW_PROCESSING | Em processamento no PSP / SPI. | Não | — |
WITHDRAW_APPROVED | Saque concluído — o SPI confirmou a liquidação. | ✅ | cashout.success |
WITHDRAW_RETURNED | Devolvido pelo banco do recebedor (chave inválida, conta encerrada, etc.). O valor é re-creditado no seu saldo. | ✅ | cashout.returned |
WITHDRAW_PARTIALLY_RETURNED | Devolvido parcialmente pelo banco do recebedor — parte do valor volta ao seu saldo; a taxa é mantida. | ✅ | cashout.returned |
WITHDRAW_REJECTED | Recusado na validação (saldo insuficiente, chave inválida, limites). | ✅ | — |
WITHDRAW_ERROR | Falha técnica no envio do saque. | ✅ | cashout.failed |
"Final?" indica se o status é terminal (não muda mais).
WITHDRAW_PARTIALLY_RETURNEDtambém é terminal. Os não-finais ainda podem transicionar — ex.:WITHDRAW_PROCESSING→WITHDRAW_APPROVED,WITHDRAW_RETURNEDouWITHDRAW_PARTIALLY_RETURNED.
Detalhes dos payloads por evento em Payload v2 e Payload v1.
Glossário — motivos de cancelamento
Por que um depósito (cash-in) ou um saque (cash-out) não se concretiza — causa, status resultante e o que fazer. Em recusa de cartão, o motivo detalhado vem em decline_category; em devolução de Pix, o texto do banco do recebedor vem no errorMessage/error_message do webhook.
Depósitos (cash-in)
| Motivo | O que significa | Status | O que fazer |
|---|---|---|---|
| Não pago / PIX expirado | O comprador não pagou dentro do prazo do QR. | CANCELED (ou PENDING sem pagamento) | Gere uma nova cobrança. |
| Recusa do emissor (cartão) | O banco emissor não autorizou. Sub-motivo em decline_category: issuer_declined, insufficient_funds, invalid_card, expired_card, suspected_fraud. Resposta HTTP 402. | REJECTED | Mostre a message ao comprador e peça outro cartão. Não retente o mesmo automaticamente. |
| Recusa do PSP | A transação foi negada no processamento (fora cartão). | REJECTED | Nenhum crédito foi gerado. Ajuste e tente de novo se fizer sentido. |
| Valor pago ≠ cobrado | O pagador enviou um valor diferente do cobrado. | INCOSISTENT | Não entregue nem estorne automaticamente. Abra um ticket com o transaction_id. |
| Bloqueio por MED / compliance (Pix) | Saldo retido por disputa / infração. | BLOCKED | Valor fica retido até a resolução da disputa (evento infraction.updated). |
| Chargeback (cartão) | Contestação aberta pelo portador. | CHARGEBACK | Responda pelo fluxo de disputa/infração. |
| Estorno | O valor foi devolvido ao pagador (solicitado por você ou pelo suporte). | REFUNDED (ou REFUNDED_PROCESSING) | Operação concluída; confirme pelo cashin.refunded. |
| Erro técnico | Falha durante o processamento. | ERROR | Estado incerto — reconcilie por externalId antes de qualquer ação; pode valer retry. |
Saques (cash-out)
| Motivo | O que significa | Status | O que fazer |
|---|---|---|---|
| Saldo insuficiente | O saldo disponível não cobre o valor + taxa no momento da validação. | WITHDRAW_REJECTED | Confira o saldo disponível e reenvie. |
| Chave Pix inválida / inexistente | A chave informada não existe ou é inválida. Pode ser barrada na validação ou aceita e depois devolvida pelo banco do recebedor. | WITHDRAW_REJECTED ou WITHDRAW_RETURNED | Corrija a chave antes de reenviar. |
| Fora de limites | Valor abaixo do mínimo, acima do máximo ou além do limite da conta. | WITHDRAW_REJECTED | Ajuste o valor aos limites da conta. |
| Conta do recebedor encerrada / bloqueada | O banco do recebedor recusou o crédito e devolveu o valor. | WITHDRAW_RETURNED | O valor volta ao seu saldo. Verifique os dados do recebedor. |
| Devolução pelo banco do recebedor (total ou parcial) | O Pix foi aprovado e depois devolvido — integral ou em parte. | WITHDRAW_RETURNED / WITHDRAW_PARTIALLY_RETURNED | O valor (ou a parte devolvida) volta ao saldo; a taxa é mantida. Investigue antes de tentar de novo. |
| Falha técnica / timeout no envio | Erro ao enviar o saque ao SPI. | WITHDRAW_ERROR | Os fundos voltam ao saldo (cashout.failed). Reconcilie por externalId antes de reenviar — reenviar com o mesmo externalId é idempotente (não debita de novo). |
| Cash-out desabilitado na conta | Saques temporariamente bloqueados para a sua conta. | recusa na solicitação | Fale com o suporte. |
Devolução ≠ recusa.
WITHDRAW_REJECTEDé barrado antes de sair (nenhum valor saiu).WITHDRAW_RETURNED/WITHDRAW_PARTIALLY_RETURNEDé devolvido depois de aprovado — o valor chegou a sair e voltou. Em ambos o saldo é re-creditado; só na devolução (WITHDRAW_RETURNED/WITHDRAW_PARTIALLY_RETURNED) a taxa é mantida.