Mapeamento de Status de Pagamento
Três sistemas rastreiam status de forma independente: WooCommerce (status do pedido), Stripe (status de pagamento/fatura) e MIDDAG Account (status do entitlement). Esta página mapeia como eles se relacionam e o que dispara cada transição.
Fluxo de status nos três sistemas
Tabela de mapeamento completa
Compra inicial
| Status do Pedido WC | Status do Pagamento Stripe | Status do Entitlement | O que aconteceu |
|---|---|---|---|
| Pending | -- | (nenhum) | Pedido criado, aguardando pagamento |
| On Hold | -- | (nenhum) | Aguardando pagamento manual (Boleto gerado) |
| Processing | Incomplete | (nenhum) | Pagamento iniciado, ainda não confirmado |
| Processing | Requires Action | (nenhum) | Verificação 3D Secure / SCA necessária |
| Completed | Succeeded | Active | Pagamento confirmado, entitlement criado |
| Failed | Failed | (nenhum) | Pagamento recusado, sem entitlement |
| Cancelled | -- | (nenhum) | Pedido abandonado ou expirado, sem entitlement |
Renovação de assinatura
| Evento da Assinatura WC | Status da Fatura Stripe | Status do Entitlement | O que aconteceu |
|---|---|---|---|
| Renovação paga | Paid | Active | Renovação bem-sucedida, expiração estendida |
| Renovação falhou | Past Due | Active (carência) | Primeira falha, Stripe fará retentativa |
| Retentativas esgotadas | Uncollectible | Suspended | Todas as tentativas falharam |
| Pagamento recuperado | Paid | Active | Pagamento tardio recebido, reativado automaticamente |
| Assinatura expirada | -- | Expired | Período de cobrança encerrado sem renovação |
| Assinatura cancelada | -- | Expired | Cliente ou admin cancelou, ativo até o fim do período |
Reembolso e disputa
| Status do Pedido WC | Status do Pagamento Stripe | Status do Entitlement | O que aconteceu |
|---|---|---|---|
| Refunded | Refunded | Cancelled | Reembolso total processado |
| Refunded | Partially Refunded | Active | Reembolso parcial, entitlement inalterado |
| -- | Disputed | Suspended | Chargeback registrado, entitlement suspenso |
| -- | Dispute won | Active | Chargeback revertido, entitlement restaurado |
| Refunded | Dispute lost | Cancelled | Chargeback mantido, entitlement cancelado |
Gatilhos de transição
Cada transição de status do entitlement é disparada por um evento específico:
| De | Para | Gatilho | Política consultada |
|---|---|---|---|
| (nenhum) | Active | woocommerce_order_status_completed | Provisioning Policy |
| Active | Suspended | Retentativa de pagamento esgotada / chargeback registrado | Payment Recovery Policy |
| Suspended | Active | Pagamento recuperado / disputa ganha | Payment Recovery Policy |
| Suspended | Cancelled | suspended_to_cancelled_days decorrido (padrão: 30) | Payment Recovery Policy |
| Active | Expired | end_date do entitlement atingida sem renovação | Renewal Policy |
| Expired | Active | Pagamento de renovação confirmado | Renewal Policy |
| Expired | Cancelled | expired_to_cancelled_days decorrido (padrão: 30) | Cancellation Policy |
| Active | Cancelled | Reembolso total / cancelamento pelo admin | Refund Policy |
| Cancelled | Active | Win-back: nova assinatura reativa o mesmo entitlement | -- |
Casos especiais
Pagamento parcial
O WooCommerce não suporta pagamentos parciais nativamente. Se um fluxo customizado permite pagamento parcial (ex.: depósito), o pedido permanece em Processing até que o valor total seja recebido. Nenhum entitlement é criado até o pedido atingir Completed.
Boleto (aguardando compensação)
Pagamentos via Boleto pelo Banco Inter levam 1-2 dias úteis para compensar. Durante esse tempo:
- Status do pedido WC: On Hold
- Status Stripe: N/A (Banco Inter, não Stripe)
- Entitlement: Ainda não criado
Quando o webhook do Banco Inter confirma o pagamento, o pedido passa para Completed e o entitlement é criado.
Pix (timeout de 30 minutos)
Pagamentos via Pix têm uma janela de 30 minutos. Se o cliente não pagar dentro dessa janela:
- O QR code expira
- O cliente pode gerar um novo QR code pelo portal (desde que a cotação não tenha expirado)
- O pedido permanece em Pending até o pagamento ou timeout
Stripe 3D Secure (SCA)
Quando o Stripe requer verificação 3D Secure:
- Status do pedido WC: Processing (ou Pending, dependendo da configuração do gateway)
- Status Stripe: Requires Action
- Entitlement: Ainda não criado
Se o cliente abandona o fluxo 3D Secure, o pagamento falha e nenhum entitlement é criado.
Atualização de método de pagamento durante suspensão
Quando um entitlement é suspenso por falha de pagamento, o cliente pode atualizar seu método de pagamento pelo portal. Na próxima retentativa do Stripe (ou cobrança imediata), se bem-sucedida:
- Status Stripe: Succeeded
- Assinatura WC: Active
- Entitlement: Retorna para Active automaticamente
Monitoramento
Os admins podem monitorar a saúde do pipeline dos três sistemas através de:
- MIDDAG Account > Dashboard -- Entitlements por status (ativo, suspenso, expirado, cancelado)
- WooCommerce > Pedidos -- Pedidos por status
- MIDDAG Account > Logs -- Eventos de provisionamento, processamento de webhooks, erros de sincronização
- Cron de reconciliação -- Roda a cada 15 minutos para detectar divergências entre Stripe e registros locais
Páginas relacionadas
- Pedidos e Entitlements -- pipeline pedido-para-entitlement
- Renovações -- mecânica de renovações e falha de pagamento
- Reembolsos e Cancelamentos -- impacto de reembolsos e cancelamentos
- Impostos e Faturas -- mapeamento de status de faturas
- Pedidos -- referência do conceito de pedido