BrazilianHubBrazilianHubdocs

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 status da 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)

StatusSignificadoFinal?Evento webhook
PENDINGCobrança criada, aguardando pagamento (PIX não pago ou cartão não capturado).Não—
APPROVEDPagamento confirmado e valor creditado no seu saldo.✅cashin.paid
REJECTEDRecusada pelo PSP/emissor (ex.: cartão negado). Nenhum crédito é gerado.✅—
CANCELEDCancelada antes do pagamento (expiração do PIX ou cancelamento).✅—
REFUNDEDEstornada com sucesso — o valor voltou ao pagador.✅cashin.refunded
REFUNDED_PROCESSINGEstorno solicitado e em processamento (ainda não concluído).Não—
CHARGEBACKContestação de cartão (chargeback) aberta pelo portador.Nãoinfraction.updated
BLOCKEDSaldo retido por MED / disputa de compliance (Pix).Nãoinfraction.updated
INCOSISTENTValor pago ≠ valor cobrado. Anomalia — não entregue nem estorne automaticamente; abra um ticket com o transaction_id.Nãocashin.paid (com status embutido)
ERRORFalha técnica durante o processamento.✅—

Status de saque (cash-out)

StatusSignificadoFinal?Evento webhook
WITHDRAW_INFORMATIONRegistro informativo/interno anterior à solicitação.Não—
WITHDRAW_REQUESTSaque solicitado e na fila para processamento.Não—
WITHDRAW_PROCESSINGEm processamento no PSP / SPI.Não—
WITHDRAW_APPROVEDSaque concluído — o SPI confirmou a liquidação.✅cashout.success
WITHDRAW_RETURNEDDevolvido pelo banco do recebedor (chave inválida, conta encerrada, etc.). O valor é re-creditado no seu saldo.✅cashout.returned
WITHDRAW_PARTIALLY_RETURNEDDevolvido parcialmente pelo banco do recebedor — parte do valor volta ao seu saldo; a taxa é mantida.✅cashout.returned
WITHDRAW_REJECTEDRecusado na validação (saldo insuficiente, chave inválida, limites).✅—
WITHDRAW_ERRORFalha técnica no envio do saque.✅cashout.failed

"Final?" indica se o status é terminal (não muda mais). WITHDRAW_PARTIALLY_RETURNED também é terminal. Os não-finais ainda podem transicionar — ex.: WITHDRAW_PROCESSING → WITHDRAW_APPROVED, WITHDRAW_RETURNED ou WITHDRAW_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)

MotivoO que significaStatusO que fazer
Não pago / PIX expiradoO 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.REJECTEDMostre a message ao comprador e peça outro cartão. Não retente o mesmo automaticamente.
Recusa do PSPA transação foi negada no processamento (fora cartão).REJECTEDNenhum crédito foi gerado. Ajuste e tente de novo se fizer sentido.
Valor pago ≠ cobradoO pagador enviou um valor diferente do cobrado.INCOSISTENTNão entregue nem estorne automaticamente. Abra um ticket com o transaction_id.
Bloqueio por MED / compliance (Pix)Saldo retido por disputa / infração.BLOCKEDValor fica retido até a resolução da disputa (evento infraction.updated).
Chargeback (cartão)Contestação aberta pelo portador.CHARGEBACKResponda pelo fluxo de disputa/infração.
EstornoO 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écnicoFalha durante o processamento.ERROREstado incerto — reconcilie por externalId antes de qualquer ação; pode valer retry.

Saques (cash-out)

MotivoO que significaStatusO que fazer
Saldo insuficienteO saldo disponível não cobre o valor + taxa no momento da validação.WITHDRAW_REJECTEDConfira o saldo disponível e reenvie.
Chave Pix inválida / inexistenteA 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_RETURNEDCorrija a chave antes de reenviar.
Fora de limitesValor abaixo do mínimo, acima do máximo ou além do limite da conta.WITHDRAW_REJECTEDAjuste o valor aos limites da conta.
Conta do recebedor encerrada / bloqueadaO banco do recebedor recusou o crédito e devolveu o valor.WITHDRAW_RETURNEDO 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_RETURNEDO valor (ou a parte devolvida) volta ao saldo; a taxa é mantida. Investigue antes de tentar de novo.
Falha técnica / timeout no envioErro ao enviar o saque ao SPI.WITHDRAW_ERROROs 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 contaSaques temporariamente bloqueados para a sua conta.recusa na solicitaçãoFale 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.