Multi-Entity Operations
MIDDAG operates as two legal entities: MIDDAG BR (Brazilian company, Brasilia/DF) and MIDDAG GLOBAL (US LLC). MIDDAG Account routes every financial transaction, integration call, and tax operation to the correct entity. This page explains how that routing works and what it affects.
The two entities
| Attribute | MIDDAG BR | MIDDAG GLOBAL (LLC) |
|---|---|---|
| Legal jurisdiction | Brazil (Brasilia/DF) | United States |
| Currency | BRL (Brazilian Real) | USD (US Dollar) |
| Payment gateway | Stripe BR + Banco Inter (Pix/Boleto) | Stripe GLOBAL (card only) |
| CRM | HubSpot BR portal | HubSpot GLOBAL portal |
| Tax invoices | NFSe via ISSNet (mandatory for services) | None (no NFSe requirement) |
| Stripe account | Separate account (middag_br) | Separate account (middag_global) |
How entity routing works
Every transaction in MIDDAG Account carries an entity context. The system determines the correct entity using a resolution chain:
The resolution priority:
- Explicit billing entity on the Organization (most reliable -- set during onboarding).
- Tax ID type -- CNPJ routes to BR; EIN/VAT routes to GLOBAL.
- Product entity tag -- Products in the catalog can specify which entity they belong to.
- Currency fallback -- BRL implies BR, USD implies GLOBAL.
- Admin override -- The admin can override entity routing per transaction.
What entity context affects
Stripe account selection
Each entity has its own Stripe account with separate API keys, webhook secrets, and customer records. When processing a payment:
- BR transactions go through the
middag_brStripe account. - GLOBAL transactions go through the
middag_globalStripe account. - Webhook endpoints are separated:
/webhooks/stripe/brand/webhooks/stripe/llc. - Invoice records are tagged with the originating Stripe account for filtering.
Payment methods
| Entity | Credit card | Pix | Boleto |
|---|---|---|---|
| BR | Yes (Stripe) | Yes (Banco Inter) | Yes (Banco Inter) |
| GLOBAL | Yes (Stripe) | No | No |
BR customers have access to local Brazilian payment methods. GLOBAL customers use credit card only.
HubSpot CRM
Each entity has its own HubSpot portal:
- Deals, quotes, and contacts are synced to the correct portal based on entity.
- Quote webhooks carry the
hubspot_accountidentifier (middag_brormiddag_global). - Status updates (quote accepted, paid) are synced back to the originating portal.
Tax invoices
- BR transactions trigger automatic NFSe (tax invoice) issuance via ISSNet.
- GLOBAL transactions do not generate tax invoices. The Stripe invoice serves as the financial record.
Pricing
Products can have dual pricing:
- A BRL price for BR customers.
- A USD price for GLOBAL customers.
The system uses fixed dual prices when configured, or falls back to configurable exchange rate bands. BR pricing is intentionally positioned higher than GLOBAL pricing to incentivize international purchases through the LLC.
Organization-level configuration
An Organization can have identifiers for both entities simultaneously:
| Field | Purpose |
|---|---|
stripe_customer_id_br | Stripe Customer ID in the BR account |
stripe_customer_id_llc | Stripe Customer ID in the GLOBAL account |
hubspot_company_id_br | HubSpot Company ID in the BR portal |
hubspot_company_id_llc | HubSpot Company ID in the GLOBAL portal |
billing_entity | Primary entity for this Organization |
This allows a single Organization to have transactions in both entities -- for example, a Brazilian company that also purchases USD-denominated products.
API-level entity context
Every API request can carry entity context via the X-Middag-Company header:
middag_br-- Scope the request to BR data.middag_global-- Scope the request to GLOBAL data.- Omitted -- Return data from both entities (unified view).
This header is used by the portal to filter invoices, orders, and quotes by entity, and by the admin panel to route operations correctly.
Cross-entity scenarios
| Scenario | How it works |
|---|---|
| BR org buys a USD product | Product's entity tag routes to GLOBAL Stripe |
| Single org, transactions in both currencies | Both Stripe Customer IDs linked; portal shows unified list |
| Quote from HubSpot BR, payment via GLOBAL | Admin overrides entity at payment time (rare) |
| NFSe needed for a GLOBAL transaction | Not supported -- NFSe is BR-only |
| Admin creates quote for either entity | Admin selects entity explicitly during creation |
Related pages
- Billing and Finance -- Invoice generation and tax invoices by entity
- Purchase and Renewal Flow -- Payment methods per entity
- Organization Onboarding -- Setting the billing entity during onboarding