Invoices

An Invoice is a financial record that tracks what was charged, when, and whether it has been paid. In MIDDAG Account, invoices come from Stripe and are synchronized automatically via webhooks. For Brazilian operations, a companion Tax Invoice (NFSe) may also be generated for tax compliance.

How invoices are created

Invoices are not created manually in MIDDAG Account. They originate in Stripe when a payment is processed -- whether from a one-time order, a subscription renewal, or a quote conversion. The system listens for Stripe webhooks and mirrors the invoice data locally.

The local record is a read-only projection of the Stripe invoice. MIDDAG Account does not modify invoices in Stripe -- it reads and displays them.

Invoice lifecycle

Invoices follow Stripe's native states:

Status	What it means
Draft	Invoice created but not yet finalized. Can still be edited in Stripe.
Open	Finalized and sent to the customer. Awaiting payment.
Paid	Payment confirmed.
Void	Cancelled before payment.
Uncollectible	Marked as unlikely to be collected.
Overdue	Past due date without payment.

The system processes twelve Stripe webhook event types to keep the local record in sync: invoice.created, invoice.updated, invoice.finalized, invoice.sent, invoice.paid, invoice.payment_failed, invoice.payment_action_required, invoice.upcoming, invoice.voided, invoice.marked_uncollectible, invoice.deleted, and invoice.overdue.

Dual-entity invoices

Each invoice is tagged with the Stripe account that generated it:

• middag_br -- Brazilian entity (BRL)
• middag_global -- US entity (USD)

The tag is determined by which webhook endpoint received the event. Admins can filter invoices by entity for financial reporting and reconciliation.

Link to entitlements

Invoices are linked to entitlements indirectly, through orders:

Invoice --> Order (via stripe_invoice_id) --> Entitlement

This means every invoice is traceable back to the entitlement it supports, giving you a complete financial history for any customer access record.

PDF download

Invoice PDFs are available from Stripe. When a customer or admin requests a PDF, the system redirects to Stripe's hosted invoice URL or PDF download URL. If a Stripe-hosted PDF is unavailable, a custom PDF can be generated locally and stored in Cloudflare R2.

Reconciliation

A cron job runs every 15 minutes to reconcile local invoice records with Stripe. This catches any webhooks that were missed or failed, ensuring the local database stays consistent with Stripe's data. The cron uses a lock to prevent concurrent execution.

Tax Invoices (NFSe)

For transactions processed through MIDDAG BR, a Tax Invoice (NFSe -- Nota Fiscal de Servico Eletronica) may be issued for Brazilian tax compliance. NFSe are generated through integration with ISSNet, the municipal tax authority web service for Brasilia/DF.

When NFSe are generated

NFSe are triggered automatically when a payment is confirmed for a MIDDAG BR transaction:

1. Stripe webhook confirms payment.
2. System identifies the transaction as MIDDAG BR.
3. Tax invoice service builds the XML document with provider (MIDDAG) and recipient (organization) data.
4. The XML is submitted to ISSNet via SOAP API.
5. If accepted immediately, the NFSe is stored with status issued.
6. If pending, a cron job polls ISSNet every 5 minutes until the status is resolved.

NFSe are not generated for MIDDAG GLOBAL transactions or for zero-value transactions.

NFSe states

Status	What it means
Pending	Submitted to ISSNet, awaiting confirmation.
Issued	Accepted by ISSNet. Verification code assigned.
Rejected	ISSNet rejected the submission. Admin notified.
Cancelled	Admin cancelled the NFSe with justification.

Manual NFSe issuance

Admins can issue NFSe manually from the WordPress admin when automatic issuance fails or when issuing for a transaction that did not trigger automation. The admin reviews pre-filled data (provider, recipient, service description, tax rates) and submits.

Customer access

Customers see both commercial invoices (from Stripe) and tax invoices (NFSe) in a unified list in the portal, with a visual indicator distinguishing the two types. Customers can download the XML (for tax compliance) and PDF for each NFSe.

What admins see

The invoice list in the WordPress admin shows:

• Invoice number
• Organization
• Amount and currency
• Status (with color indicators)
• Entity (MIDDAG BR or MIDDAG GLOBAL)
• Date issued and date paid
• Link to the associated order and entitlement

Admins can filter by entity, status, date range, and organization.

Related pages

• Orders -- the purchases that generate invoices
• Entitlements -- the access records invoices are traced back to
• Legal Entities -- how transactions are routed to the correct entity
• Quotes -- proposals that convert into orders and invoices