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 (classification, exemption, regime) — 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:

When the payment is a Stripe invoice (invoice.paid) and neither the Stripe invoice nor the Stripe customer carries an address country, BeeL. reads it from the billing address of the charge that paid the invoice. It is used last: any address the invoice or customer carries wins, and the charge only supplies the country when the chosen address has none. This way invoice.paid and the payment event of the same charge see the same buyer, and the country decides how the sale is taxed.

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.

Shipping charged without VAT

Shipping is part of the sale it delivers, so Spanish law taxes it at the sale's rate (art. 78.Dos.1º LIVA). When Stripe charged shipping with no tax rate and no taxability reason, on a sale that does carry VAT, BeeL. invoices the shipping as an ancillary cost:

• The shipping amount Stripe charged is read as tax-inclusive at the sale's VAT rate, so the invoice total is still exactly what Stripe charged.
• If the sale mixes several rates, the shipping is split between them in proportion to each rate's base.
• The share that belongs to an exempt or non-taxable part of the sale goes out exempt, with that part's own exemption reason and no tax.
• Tips and discounts are not part of that split.

Coupons and discounts (Stripe Billing)

A Stripe Invoice paid with a coupon is invoiced for what was charged, not for the gross line. The sale line keeps its full price and the discount goes on a separate line with a negative quantity, so sale minus discount equals the amount Stripe collected. The discount line carries its share of the tax too, so the invoice's total tax is the tax Stripe calculated on the discounted amount.

A credit note on a discounted invoice credits the discounted amount as well — see Generated invoices.

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: this is a BeeL. rule, not a statement about who must withhold. If BeeL. applied your default professional IRPF (e.g. 15 %), the invoice total would diverge from the Stripe charge — violating Fiscal Mirror.

If a customer withholds IRPF from what they pay you, don't issue that invoice through Stripe — issue it through 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 event was retried after a configuration change — the retry applied the new configuration
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 building the invoice, BeeL. checks a few fields of the Stripe payload and trims or annotates the ones that would otherwise make the invoice fail. Every modification is recorded with the resulting invoice, so the change can be audited.

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 is recorded with the resulting invoice. Those records are not exposed through 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 left in Needs attention, Necesita atención in the dashboard, depending on the 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 what to do next.

Forward vs corrective routing

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

• Forward route — issues a brand-new F1 / F2 (forward invoice) with a fresh number against the resolved series.
• Corrective route — looks up the original BeeL. invoice via the Stripe payment identifier and issues an R1 / R4 / R5 corrective invoice (factura 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.

What each route takes from where

• A forward invoice resolves its recipient from the Stripe payment (optionally creating the customer mapping), picks F1 or F2 as described in Generated invoices, and takes the next number of the series.
• A corrective never resolves a recipient of its own: it copies the recipient of the original invoice. The Stripe reason is mapped to a rectification code, and the tax-inclusive mode and IVA rate are taken from the original, so the corrective nets against it exactly.

What happens when the corrective 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 waits with reason REFUND_ORIGINAL_NOT_FOUND and BeeL. retries it automatically — up to 8 times, about a day in all; once the payment arrives and creates the original, the next retry of the refund produces its rectificativa. See the Necesita atención section in Edge cases and limits.

Idempotency on both sides

Both routes deduplicate by the Stripe identifier of what they invoice:

• A forward invoice is deduplicated by the Stripe payment: processing the same payment_intent.succeeded again always resolves to the same invoice, even when two deliveries race each other.
• A corrective is deduplicated by the Stripe refund or credit-note ID: processing the same re_... or cn_... again always resolves to the same corrective.

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

Related