# Docs

Fattura.dev is the simplest way to send Italian e-invoices for Stripe payments. It turns every payment into an electronic invoice in the FatturaPA format and transmits it to the Sistema di Interscambio (SdI), the exchange system run by Italy's tax agency. There is no code to write: you connect Stripe, enter the VAT number, and from then on it is automatic.

## Italy in one paragraph

Every Italian business must issue its invoices as XML files in a format called FatturaPA and send them through the SdI, which validates each file and delivers it to the customer. An invoice that never went through the SdI does not legally exist. If you build or sell for the Italian market with Stripe, this is the step Stripe leaves to you, and the step Fattura.dev takes over.

## Quick start

1. **Create the account** at [fattura.dev/en/login](/en/login) with Google or your email.
2. **Connect Stripe.** One click where available, or paste a restricted API key (read-only, plus permission to create the webhook).
3. **Enter the VAT number** (partita IVA). Company name and address are read from the EU VAT register (VIES); choose the tax regime and save.

The first 10 invoices are free and no card is needed. The seller must hold an Italian VAT number. A developer or agency can do the setup once on a client's Stripe account.

## Which payments become a document

| Stripe event | What we issue |
|---|---|
| `invoice.paid` (Billing, subscriptions, Stripe invoices) | Invoice `TD01` |
| `checkout.session.completed` in `payment` mode | Invoice `TD01` |
| `charge.succeeded` with no Checkout and no Stripe invoice (a direct PaymentIntent) | Invoice `TD01` |
| `charge.refunded` | Credit note `TD04` for the refunded amount |
| `credit_note.created` (the part not refunded through Stripe) | Credit note `TD04` |

Each Stripe object produces at most one document: if Stripe redelivers an event, nothing happens. The invoice date is the day of the payment in Italian time, and it is sent straight away, well inside the 12 days allowed for an immediate invoice.

## Customer data: where we read it

For each field we use the first value we find, in this order: corrections you entered in the dashboard, the event's own data (Stripe invoice or Checkout session), the Customer object.

| Invoice field | Where we read it on Stripe |
|---|---|
| Name | `business_name`, then `name` |
| VAT number | Tax ID of type `eu_vat` (or another `*_vat`); otherwise metadata `partita_iva` |
| Codice fiscale (personal tax code) | Tax ID of type `it_cf`; otherwise a custom field or metadata `codice_fiscale` |
| Street, postcode, city, province, country | Billing address (`address`) |
| SdI recipient code | Custom field or metadata `codice_destinatario` (also `sdi`) |
| PEC (certified email) | Custom field or metadata `pec` |

Field and metadata names ignore case, spaces and underscores: `Codice Fiscale`, `codice_fiscale` and `codicefiscale` are the same.

When the recipient code is missing we use `0000000`: the invoice is valid and the customer finds it in their private area on the tax agency's site. For foreign customers we use `XXXXXXX`.

## Checkout: collect the right data

Three options when you create the session collect everything that is needed:

```js
const session = await stripe.checkout.sessions.create({
  mode: "payment",
  line_items: [{ price: "price_123", quantity: 1 }],

  // Billing address: mandatory on every invoice.
  billing_address_collection: "required",

  // VAT number for business customers.
  tax_id_collection: { enabled: true },

  // Codice fiscale for consumers who want an invoice; recipient code for businesses.
  custom_fields: [
    {
      key: "codice_fiscale",
      label: { type: "custom", custom: "Codice fiscale (se vuoi la fattura)" },
      type: "text",
      optional: true,
    },
    {
      key: "codice_destinatario",
      label: { type: "custom", custom: "Codice destinatario SdI" },
      type: "text",
      optional: true,
    },
  ],

  success_url: "https://example.com/thanks",
});
```

With Stripe Billing or Stripe invoices, store the same data on the Customer: address, Tax ID and, when you have them, the metadata `codice_fiscale` and `codice_destinatario`.

If a payment lacks mandatory data the document stays in the status **Mancano dati** (data missing): we email you, you complete the fields in the dashboard, and it goes out. The correction is remembered for that customer's next payments.

## Consumers

For online sales to consumers an invoice is not mandatory unless the customer asks for one no later than the purchase. So the default is: **we invoice consumers only when they give their codice fiscale**. Other consumer payments appear in the dashboard as *Non emessa* (not issued).

You can choose to invoice everyone instead: consumer payments without a codice fiscale then wait until you enter it. Reporting of sales that are not invoiced (corrispettivi) remains the seller's job: the seller's accountant will know which rules apply.

## VAT: the rules applied

The amount charged on Stripe is always the invoice total. VAT is extracted from that total.

| Seller | Customer | Treatment |
|---|---|---|
| Ordinary regime | Italy | VAT at the rate Stripe reports (Stripe Tax or a tax rate); if Stripe reports none, your default rate (22%) |
| Ordinary regime | EU business with a VAT number, services | Nature `N2.1`, wording "Inversione contabile" (reverse charge) |
| Ordinary regime | EU business with a VAT number, goods | Nature `N3.2`, zero-rated |
| Ordinary regime | EU consumer, no foreign VAT applied by Stripe | Italian VAT |
| Ordinary regime | EU consumer, VAT of the destination country (OSS) | No electronic invoice: document *Non emessa* |
| Ordinary regime | Outside the EU, services | Nature `N2.1`, wording "Operazione non soggetta" (out of scope) |
| Ordinary regime | Outside the EU, goods | Nature `N3.1`, zero-rated |
| Forfettario | Italy, and foreign consumers | Nature `N2.2` with the statutory wording of the flat-rate regime |
| Forfettario | Foreign business with a VAT number, services | Nature `N2.1` |

What we cannot decide with certainty we do not guess: an Italian sale that Stripe taxed at 0%, for example, waits for you to check it.

## Stamp duty

On invoices without VAT (natures `N2.1`, `N2.2`, `N4`) above €77.47 we declare the €2 virtual stamp duty (bollo). It is not charged to the customer: the seller owes it and pays it each quarter from the tax agency's *Fatture e Corrispettivi* portal, which works the amount out by itself.

## Refunds and credit notes

When you refund a payment on Stripe, fully or partly, we issue a `TD04` credit note linked to the original invoice, with the same VAT rates in proportion. If the original invoice was never issued, no credit note is issued either.

## Numbering

Invoices issued by Fattura.dev use their own series, with a prefix you choose, so it never overlaps with invoices you issue elsewhere:

```text
FD-2026-00001
FD-2026-00002
```

Numbering is sequential, has no gaps and restarts from 1 each year. The Stripe invoice number, when there is one, is quoted in the invoice notes.

## Document statuses

The dashboard is in Italian. These are the statuses you will see.

| Status | Meaning |
|---|---|
| Inviata | Transmitted, waiting for the SdI receipt |
| Consegnata | Delivered to the customer |
| Non recapitata | Valid, but the SdI could not deliver it: tell the customer it is in their private area and send them a copy |
| Scartata | Rejected: it counts as never issued. Fix it and resend within 5 days; it keeps its number and date |
| Mancano dati | Customer data, or your own, is missing |
| Non emessa | No electronic invoice is needed for this sale |
| Prova | Test-mode payment: XML generated, not transmitted |

## Test mode

Connect an `rk_test_…` key (or a sandbox account) and make a test payment: the document appears in the dashboard with the status **Prova** and a downloadable XML, and it is not transmitted. You can check the result before going live.

## Archiving

Legal archiving of invoices (conservazione) is not included. The seller can use the tax agency's free service: sign in to *Fatture e Corrispettivi*, open *Fatturazione elettronica e conservazione* and accept the service agreement. It is done once, by the seller.

From the dashboard you can download the XML of every document, and you can set the accountant's email so that each XML reaches them as soon as it is transmitted.

## Who is responsible

Fattura.dev generates and transmits invoices on the seller's instruction, through an intermediary accredited with the SdI. The seller remains the issuer of the invoice and is responsible for its content. Fattura.dev processes customer data as a processor, under the [data processing agreement](/dpa) (in Italian).

## Current limits

- Payments in euro only.
- No invoices to the public administration (format `FPA12`).
- No invoices for EU consumer sales under the OSS scheme.
- No `TD17` self-invoices for Stripe's fees.
- No withholding tax and no professional pension fund contributions.

## Use it from Claude or ChatGPT

Fattura.dev has a connector for AI assistants. Once connected you can ask things like "how many invoices did I send this month?", "which invoices are held and why?" or "complete Mario Rossi's invoice with this codice fiscale and send it".

Connector address:

```text
https://fattura.dev/api/mcp
```

Add it as a custom connector in Claude or ChatGPT and sign in with your Fattura.dev account when asked. In Claude Code:

```bash
claude mcp add --transport http fattura https://fattura.dev/api/mcp
```

The assistant can see invoices, statuses and the month's summary, download the XML, and complete the data of a held invoice to send it when you ask. It cannot see or change the Stripe credentials or the subscription.

## Set it up with an AI assistant

If you use Claude Code, Cursor or another assistant, paste this prompt into your project:

```text
My project takes payments with Stripe and I use Fattura.dev (https://fattura.dev/en/docs)
to issue Italian electronic invoices. Fattura.dev reads customer data from Stripe.
Find where I create Checkout Sessions and Customers and make sure that:
1. Checkout Sessions have billing_address_collection: "required" and
   tax_id_collection: { enabled: true };
2. Checkout Sessions have two optional custom_fields of type text, with keys
   "codice_fiscale" and "codice_destinatario";
3. when I create or update a Customer I store the address and Tax ID (eu_vat for
   businesses, it_cf for consumers) and, when I have them, the metadata codice_fiscale
   and codice_destinatario.
Do not change prices, products or payment logic.
```

## Questions

### Do I need to write code?

No. Connecting Stripe and sending are automatic. The code above only makes Checkout collect your customers' tax data, if it does not already.

### Does it work for the forfettario regime?

Yes. Choose "Forfettario" in the tax data: invoices carry no VAT, nature `N2.2`, the statutory wording, and virtual stamp duty when due.

### What happens if the SdI rejects an invoice?

We email you the reason. You fix the data in the dashboard and we resend it with the same number and date.

### Can I pause issuing?

Yes, in the settings. While paused, new payments produce no documents.

### How do I cancel?

From the billing portal, which you reach from the dashboard. Cancellation takes effect at the end of the period already paid.

### Is Fattura.dev a Stripe product?

No. It is an independent service that connects to your Stripe account with read-only permissions.