Para o negócio: a regra mais segura é liberar pedido, envio ou acesso somente com a cobrança em
paid e sem bloqueio (isBlocked diferente de true). Os demais status pedem espera, uma ação do cliente ou um tratamento de pós-venda, como mostram as tabelas.Status da cobrança
Lista de valores do campostatus em POST /v1/charges, GET /v1/charges, GET /v1/charges/{id} e nos webhooks de cobrança.
Fluxos típicos
O desenho abaixo mostra como a cobrança sai da criação e chega a um resultado.
Se o comprador abandona a autenticação, a cobrança fica em
authentication_required, sem expiração automática e sem webhook.
Como o status chega até você
Formato dos eventos: Catálogo de eventos.
Bloqueio (isBlocked)
O bloqueio é uma marcação, separada do status. Uma cobrança bloqueada continua paid e passa a ter isBlocked: true, blockedAt e blockedReason (no envelope padrão do webhook, is_blocked, blocked_at e blocked_reason). Na API não existe status nem evento chamado MED ou chargeback em análise: o integrador vê essa marcação.
MED e chargeback
O MED é diferente do bloqueio cautelar do Pix, que é outra ferramenta: uma retenção preventiva e curta feita pela instituição do recebedor quando suspeita de fraude. Na API, os dois aparecem da mesma forma, como bloqueio da cobrança.
O desenho abaixo mostra o que pode acontecer com uma cobrança depois de paga, inclusive o bloqueio, que não muda o status.
1
Bloqueio recebido
Ao receber
charge.blocked (ou charge.updated com isBlocked: true), identifique a cobrança por data.id e marque o pedido como “em disputa”.2
Defesa
Não existe rota de API para enviar defesa de MED ou de chargeback. O alerta de chargeback ou MED chega por e-mail à conta (no Connect, à conta master), e a defesa com as evidências é enviada em resposta a esse e-mail, dentro do prazo indicado nele. Dúvidas, pelo suporte. Detalhes em Bloqueio, chargeback e MED.
3
Desfecho
Como a liberação não gera aviso, consulte periodicamente
GET /v1/charges/{id} das cobranças em disputa. isBlocked: false: restaure o pedido. status refunded ou chargeback: registre a perda e acione o cancelamento.Status do estorno
Resposta dePOST /v1/refunds. É o status da operação de estorno, separado do status da cobrança.
Hoje a API devolve só
refunded. Prazos, casos especiais e o que fazer se o comprador não receber estão em Estorno.
Status da assinatura
Campostatus de POST /v1/subscriptions, GET /v1/subscriptions, GET /v1/subscriptions/{id} e dos webhooks subscription.*. Na criação, os status possíveis são active e pending_activation.
O desenho abaixo mostra o ciclo de vida da assinatura.
Uma assinatura em
pending_activation com a primeira cobrança recusada não é cobrada de novo. Para tentar outro cartão, crie uma nova assinatura.
Status da cobrança dentro da assinatura
No históricocharges de GET /v1/subscriptions/{id}. Há uma linha por tentativa: as retentativas recusadas de um ciclo repetem o mesmo billingCycle.
Status do cartão salvo
Os valores dependem da rota.
Para saber se um cartão pode ser usado em
POST /v1/charges, use a listagem GET /v1/cards: a cobrança recusa cartão revoked ou expired.
Status da subconta (Connect)
Campostatus de GET /v1/submerchants e GET /v1/submerchants/{merchantId}. Só a subconta active opera.
Fluxo comum:
pending → pre_approved → active. Pedidos de correção levam a correcting, e a conta volta a pending quando os dados são reenviados. O aviso de status vai para a URL de aviso de status da subconta, como explica Webhooks de conta.
O desenho abaixo mostra o fluxo comum de aprovação da subconta e o ciclo de correção.
Os status rejected, blocked e inactive estão na tabela acima.
Status do saque
Status de uma solicitação de saque, da própria conta ou de subconta.
Só os saques de subconta geram webhook. O saque da própria conta é acompanhado pela listagem de saques.
Status do plano de assinatura
Veja também
Catálogo de eventos
Todos os eventos de webhook e seus formatos.
Bloqueio, chargeback e MED
Como funciona a disputa e a defesa.
Ciclo de vida da assinatura
Renovação, retentativa e cancelamento.
Subcontas e KYC
Cadastro e aprovação de subcontas.

