Skip to main content
O status diz em que ponto da vida um objeto está. Esta página reúne todos os status documentados da API, começando pela cobrança, que é o mais usado. Use-a como referência para decidir quando liberar um pedido, quando avisar o cliente e quando abrir um tratamento de disputa.
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 campo status 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.
O status chargeback e as recusas assíncronas chegam só pelo charge.updated, que vai somente para o postbackUrl da cobrança. No chargeback, os endpoints recebem apenas o charge.refunded, e só quando o valor é revertido do saldo. Se a sua integração não informa postbackUrl, acompanhe essas cobranças por GET /v1/charges/{id}.

Status do estorno

Resposta de POST /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

Campo status 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órico charges 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)

Campo status 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.