Payment Status Mapping
Three systems track status independently: WooCommerce (order status), Stripe (payment/invoice status), and MIDDAG Account (entitlement status). This page maps how they relate and what triggers each transition.
Three-system status flow
Complete mapping table
Initial purchase
| WC Order Status | Stripe Payment Status | Entitlement Status | What happened |
|---|---|---|---|
| Pending | -- | (none) | Order created, awaiting payment |
| On Hold | -- | (none) | Awaiting manual payment (Boleto generated) |
| Processing | Incomplete | (none) | Payment initiated, not yet confirmed |
| Processing | Requires Action | (none) | 3D Secure / SCA verification needed |
| Completed | Succeeded | Active | Payment confirmed, entitlement created |
| Failed | Failed | (none) | Payment declined, no entitlement |
| Cancelled | -- | (none) | Order abandoned or timed out, no entitlement |
Subscription renewal
| WC Subscription Event | Stripe Invoice Status | Entitlement Status | What happened |
|---|---|---|---|
| Renewal paid | Paid | Active | Renewal successful, expiration extended |
| Renewal failed | Past Due | Active (grace) | First failure, Stripe will retry |
| Retries exhausted | Uncollectible | Suspended | All retry attempts failed |
| Payment recovered | Paid | Active | Late payment received, auto-reactivated |
| Subscription expired | -- | Expired | Billing period ended without renewal |
| Subscription cancelled | -- | Expired | Customer or admin cancelled, active until period end |
Refund and dispute
| WC Order Status | Stripe Payment Status | Entitlement Status | What happened |
|---|---|---|---|
| Refunded | Refunded | Cancelled | Full refund processed |
| Refunded | Partially Refunded | Active | Partial refund, entitlement unchanged |
| -- | Disputed | Suspended | Chargeback filed, entitlement suspended |
| -- | Dispute won | Active | Chargeback reversed, entitlement restored |
| Refunded | Dispute lost | Cancelled | Chargeback upheld, entitlement cancelled |
Transition triggers
Each entitlement status transition is triggered by a specific event:
| From | To | Trigger | Policy consulted |
|---|---|---|---|
| (none) | Active | woocommerce_order_status_completed | Provisioning Policy |
| Active | Suspended | Payment retry exhausted / chargeback filed | Payment Recovery Policy |
| Suspended | Active | Payment recovered / dispute won | Payment Recovery Policy |
| Suspended | Cancelled | suspended_to_cancelled_days elapsed (default: 30) | Payment Recovery Policy |
| Active | Expired | Entitlement end_date reached without renewal | Renewal Policy |
| Expired | Active | Renewal payment confirmed | Renewal Policy |
| Expired | Cancelled | expired_to_cancelled_days elapsed (default: 30) | Cancellation Policy |
| Active | Cancelled | Full refund / admin cancellation | Refund Policy |
| Cancelled | Active | Win-back: new subscription reactivates same entitlement | -- |
Edge cases
Partial payment
WooCommerce does not natively support partial payments. If a custom flow allows partial payment (e.g., deposit), the order stays in Processing until the full amount is received. No entitlement is created until the order reaches Completed.
Boleto (awaiting clearance)
Boleto payments via Banco Inter take 1-2 business days to clear. During this time:
- WC order status: On Hold
- Stripe status: N/A (Banco Inter, not Stripe)
- Entitlement: Not yet created
When the Banco Inter webhook confirms payment, the order moves to Completed and the entitlement is created.
Pix (30-minute timeout)
Pix payments have a 30-minute window. If the customer does not pay within this window:
- The QR code expires
- The customer can generate a new QR code from the portal (as long as the quote has not expired)
- The order remains in Pending until payment or timeout
Stripe 3D Secure (SCA)
When Stripe requires 3D Secure verification:
- WC order status: Processing (or Pending, depending on gateway config)
- Stripe status: Requires Action
- Entitlement: Not yet created
If the customer abandons the 3D Secure flow, the payment fails and no entitlement is created.
Payment method update during suspension
When an entitlement is suspended due to failed payment, the customer can update their payment method through the portal. On the next Stripe retry (or immediate charge), if successful:
- Stripe status: Succeeded
- WC subscription: Active
- Entitlement: Returns to Active automatically
Monitoring
Admins can monitor the health of the three-system pipeline through:
- MIDDAG Account > Dashboard -- Entitlements by status (active, suspended, expired, cancelled)
- WooCommerce > Orders -- Orders by status
- MIDDAG Account > Logs -- Provisioning events, webhook processing, sync errors
- Reconciliation cron -- Runs every 15 minutes to detect Stripe/local divergences
Related pages
- Orders and Entitlements -- order-to-entitlement pipeline
- Renewals -- renewal mechanics and payment failure
- Refunds and Cancellations -- refund and cancellation impact
- Taxes and Invoices -- invoice status mapping
- Orders -- order concept reference