Data conversion — Stripe → BeeL

When BeeL generates an invoice from a Stripe event, it does not recalculate the operation — it reflects the Stripe charge exactly. This is the Fiscal Mirror rule and it's the single most important thing to understand about the integration. This page covers it in detail and documents every conversion BeeL applies — including the silent sanitization of inbound recipient fields and the split between the forward and rectificativa emitters that route Stripe events to the right kind of invoice.

The Fiscal Mirror rule

A Stripe charge is the fiscal truth.
BeeL's job is to translate it into a registro de facturación,
not to second-guess its tax breakdown.

In practice:

• If Stripe charged 121 €, BeeL's invoice total is 121.00 € (never 120.99 €, never 121.05 €).
• If Stripe Tax says the operation is 100 € base + 21 € IVA, BeeL's invoice carries those exact numbers.
• If Stripe Tax doesn't expose a breakdown, BeeL decomposes the charge using your configured default IVA rate treating the total as inclusive. The decomposition is exact (no residual rounding).

The only thing BeeL never copies from Stripe is the VeriFactu metadata (calificación, exención, régimen) — those depend on legal context Stripe doesn't model. BeeL infers them from your settings + the customer's geography.

Field-by-field mapping

Amounts and currency

Customer fiscal data

The resolved customer comes from Customer mappings. The conversion of fields:

Tax breakdown — Stripe Tax enabled

When you have Stripe Tax active, every charge carries tax_amounts[] per line with the rate and inclusivity flag. BeeL reads these and pre-populates each invoice line:

Stripe says:
  line { amount: 12100, tax_amounts: [{ amount: 2100, inclusive: true, rate: 21.00 }] }

BeeL emits (BeeL invoice line):
  {
    "unit_price": 100,
    "taxable_base": 100,
    "main_tax": { "type": "IVA", "percentage": 21, "regime_key": "01" },
    "line_total": 121
  }

The user's default tax configuration is not consulted when Stripe exposes a breakdown — your Stripe Tax setup wins.

Tax breakdown — Stripe Tax NOT enabled

When tax_amounts[] is empty (simple PaymentIntents, manual Stripe Invoices without Tax), BeeL falls back to your account configuration:

1. Read the connection's tax-inclusive pricing setting (per integration)
2. Read your default tax configuration (Settings > Taxes): main tax (IVA / IGIC / IPSI) and standard rate
3. Treat the Stripe total as inclusive of that rate
4. Decompose: base = total / (1 + rate/100), tax = total - base

Example: Stripe charges 121.00 €, your default is IVA 21 %, inclusive → BeeL emits base: 100.00, IVA: 21.00.

This decomposition is exact; we don't round to "round" base values. If your IVA rate is 10 % and Stripe charged 121.00 €, the base is 110.00 and the IVA is 11.00.

IRPF — always 0 on Stripe lines

Every line BeeL emits from a Stripe webhook has irpf_rate: 0 (the API field) regardless of your default IRPF configuration.

Why: Stripe Connect serves B2C scenarios (e-commerce checkouts, subscriptions to consumers, point-of-sale terminals). These are not subject to IRPF withholding under Spanish law. If BeeL applied your default professional IRPF (e.g. 15 %), the invoice total would diverge from the Stripe charge — violating Fiscal Mirror.

If you need an IRPF-withheld invoice for a customer, don't issue it through Stripe — invoice them manually via the Invoicing API with your usual settings.

VeriFactu classification

BeeL infers each line's exemption_reason (or leaves it unset for the default S1) based on the customer's geography. The full mapping lives in Tax classification; a Stripe-specific summary:

BeeL doesn't auto-detect whether you sell goods or services — set the operation type per Stripe product (in Stripe metadata) or as a connection default.

What BeeL never modifies

• The Stripe charge total — invoice total = Stripe total, always
• The currency — must be EUR; we don't convert
• The Stripe payment intent ID — kept as metadata.external_payment_id
• The Stripe customer ID — kept on the customer mapping for future matching

Reconciling discrepancies

If you spot a Stripe charge whose generated invoice has a different total, it's almost always one of:

1. A refund happened between charge and invoice generation — check for a sibling corrective
2. The webhook was replayed after a config change — the new config produced a different invoice; the original is canonical
3. Tax inclusivity flipped between Stripe Tax and the connection override — check the connection's tax-inclusive pricing toggle

For genuine mismatches that none of these explain, write to it@beel.es with the Stripe event ID and the BeeL invoice number.

Silent sanitization

Before the extracted Stripe payload reaches the invoice pipeline, BeeL runs it through a short chain of checks that trim or annotate fields that would otherwise crash downstream. The chain is ordered and explicit; every modification leaves a structured trace on the resulting invoice so the change is auditable.

The Spanish-context check for the NIF treats a payload with no country at all as Spain (BeeL's default) — so a missing country_code still triggers NIF validation, but a foreign country_code skips it.

Where the warnings end up

Every modification leaves a trace on the resulting invoice so the change is auditable from support's side. The exact location and shape of those warning records is not part of the public API today — write to it@beel.es with the invoice number if you need to trace a specific transformation.

A NIF warning means the invoice was created as a draft (or parked, depending on flow) and will be rejected at issuance with NIF_INVALID_CONTROL_DIGIT / NIF_INVALID_FORMAT. See Customer mappings for how the recipient is resolved and the Necesita atención section in Edge cases and limits for the operator workflow.

Forward vs Rectificativa routing

Stripe events fan out into two distinct routes, picked by the type of event:

• Forward route — issues a brand-new F1 / F2 / F3 (forward invoice) with a fresh number against the resolved series.
• Rectificativa route — looks up the original BeeL invoice via the Stripe payment identifier and issues an R1 / R4 / R5 (rectificativa) that mirrors the original's fiscal shape.

The full list of supported events lives in Supported events; this page only documents how each is routed.

Why the split exists

The two routes do fundamentally different things:

• The forward route is a constructor — it resolves the recipient (optionally auto-creating the customer mapping), picks the invoice type (F1 vs F2 vs simplificada based on amount, recipient address, and the connection's simplified threshold), and asks the series resolver for a fresh number.
• The rectificativa route is a mirror — it never resolves a recipient. It copies the recipient from the original invoice. The Stripe refund.reason / credit_note.reason is mapped to a VeriFactu rectification code, and the inclusive/exclusive tax mode and IVA rate are mirrored from the original so the rectificativa actually nets correctly.

Keeping the two responsibilities separate avoids a class of recurring bugs (recipient overrides on refunds, lost tax mode, wrong sign on the line totals).

What happens when the rectificativa arrives first

Stripe does not guarantee event ordering. A refund.updated can land before BeeL has seen the payment_intent.succeeded that produced the original invoice. In that case the event is parked in the inbox with reason REFUND_ORIGINAL_NOT_FOUND and sits on the retry backoff for ~6 hours; once the forward arrives and creates the original, the next replay of the rectificativa resolves cleanly. See the Necesita atención section in Edge cases and limits.

Idempotency on both sides

Both routes de-duplicate server-side by the Stripe payment identifier:

• The forward route deduplicates by the Stripe payment intent ID: replaying the same payment_intent.succeeded always resolves to the same invoice. Even under a true race between two concurrent retries, only one invoice is ever written and the Stripe retry resolves to a no-op success.
• The rectificativa route deduplicates by the Stripe refund or credit-note ID: replaying the same re_... or cn_... always resolves to the same rectificativa.

The practical guarantee is: replaying any Stripe event always yields the same BeeL invoice, never a duplicate.

Related

• Generated invoices — F1/F2 decision and series resolution
• Customer mappings — how the recipient is resolved and how to correct a bad NIF before replay
• Supported events — full event-to-handler table
• Edge cases and limits — how parked events surface and how to replay them
• VeriFactu submission — when the resulting invoice goes to AEAT