Fiscalapi for Stripe

The Fiscalapi app for the Stripe App Marketplace issues CFDI 4.0 (Mexico's electronic invoice) for the payments you receive in Stripe. A customer with tax details gets their invoice as soon as the payment is confirmed. The other payments go into the period's global invoice (factura global, one CFDI that groups a period's sales to the general public: customers who did not ask for their own CFDI), and each refund or lost dispute on an invoiced payment generates its credit note (an Egreso CFDI, type E).

Pricing

The app has no additional cost: it's included with the subscription to CFDI invoicing, and you only pay for the stamps it uses. If you already have the subscription, you don't pay anything else for the app.

Each invoice, credit note, or global invoice uses 1 stamp. The optional auto-invoice link (auto-invoice: a CFDI your customer requests from a sales receipt; you remain the issuer) requires the Auto CFDI invoicing add-on (an extra you add to your subscription).

Use cases and industries

Industries: SaaS and subscriptions, e-commerce, online education, marketplaces, and professional services that take payments with Stripe.

If your business	The app
Takes payments with Stripe and its customers request an invoice	Issues the invoice in the customer's name as soon as the payment is confirmed, with no data entry in Fiscalapi.
Sells to the general public (customers who did not ask for their own CFDI)	Issues the global invoice for each period within the SAT (Mexico's tax authority, Servicio de Administración Tributaria) deadline.
Issues refunds or loses disputes	Issues the credit note for each refund or lost dispute on an invoiced payment.
Takes payments in dollars or euros	Invoices with the FIX exchange rate that Banxico (Banco de México, Mexico's central bank) publishes; for euros, with the euro equivalence published in the DOF (Diario Oficial de la Federación, Mexico's official gazette).
Wants the customer to request their invoice later	Sends the customer a link to enter their tax details or to request their invoice in your Auto CFDI invoicing portal.

How it works

1. Link your Stripe account to your Fiscalapi tenant and choose the issuer.
2. Your customer pays in Stripe.
3. The app reads the payment, its line items and taxes, and the customer's tax details.
4. If the customer has tax details, the app issues their invoice. If not, the payment goes into the global invoice for its period.
5. The app saves the invoice's UUID on the Stripe payment and, if you turn it on, emails the invoice to the customer.
6. Each refund or lost dispute on an invoiced payment generates its credit note. Anything that couldn't be invoiced appears in Needs attention.

The app's full page, under Apps > Fiscalapi in the Stripe Dashboard, summarizes the current period and has three tabs: Overview, Needs attention, and Global invoices.

Setup

Set up the app once, in this order:

1. Sign up for Fiscalapi.
2. Activate the CFDI invoicing subscription in Compras en línea > Suscripciones (Billing > Subscriptions) and buy stamps in Compras en línea > Tienda en línea (Billing > Store), as explained in Subscription activation. If the issuer isn't the owner (the person who created the tenant), assign it stamps through a stamp transfer.
3. In Catalogos > Personas (Records > People), complete the RFC (Mexico's taxpayer ID, Registro Federal de Contribuyentes), the tax regime (régimen fiscal, the SAT category a taxpayer is registered under, such as 601 or 626), and the postal code of the issuer, and upload its current CSD.
4. Install the app and link your Stripe account.
5. Complete the required settings, such as the invoice series.

The app's Ready to invoice checklist checks each requirement and takes you to where you fix it. The app only invoices when your Fiscalapi tenant is ready to stamp.

You need the Administrator or Super Administrator role in Stripe to link your Stripe account, change the settings, assign SAT codes by product, add or edit a customer's tax details, use Import from Constancia, and run Correct invoice, Issue credit note, Invoice customer, Restore payment, Dismiss, Mark as invoiced outside the app, and Mark as issued outside the app. With any role, you can see the status of each payment and its CFDIs, run Issue invoice and Retry, download the PDF and the XML, and use Resend email.

Environments

Each Stripe mode links to its Fiscalapi environment, and the two don't mix. Stripe live mode uses live.fiscalapi.com and stamps through the production PAC (Proveedor Autorizado de Certificación, a SAT-authorized provider that stamps CFDIs), so its invoices are valid for tax purposes. Stripe test mode, or a Stripe sandbox, uses test.fiscalapi.com and stamps through the test PAC, so its invoices aren't valid for tax purposes.

To test the app in a Stripe sandbox, first sign up at test.fiscalapi.com and create a test issuer. The test data includes an RFC and a CSD you can use.

Install and link

Install Fiscalapi from the Stripe App Marketplace. While your Stripe account isn't linked, the app asks you to link it:

1. Click Link to Fiscalapi. Fiscalapi opens in a new tab.
2. Sign in with the same credentials you use for your Fiscalapi dashboard.
3. Choose the issuer that will stamp the payments, then confirm. By default, it's the tenant owner.
4. Return to Stripe. The app shows the linked issuer and the Ready to invoice checklist.

Only the owner of your Fiscalapi tenant can link a Stripe account. You see and manage the linked accounts in Configuración > Cuentas de Stripe (Settings > Stripe accounts) in your Fiscalapi dashboard. The app invoices the payments confirmed after you link your Stripe account. Invoice earlier payments from your Fiscalapi dashboard.

Settings

The settings live on the app's settings page in Stripe, with a single button to save. They apply to new payments.

In Required, you define the series for invoices, credit notes, and global invoices. You also define the SAT product or service key and the SAT unit key that a line item uses when its product has no keys of its own, and the global invoice frequency: daily, weekly, or monthly. By default, monthly.

Optional setting	What it controls
Default tax profile	The taxes used when Stripe doesn't report the payment's taxes.
Default form of payment	The SAT form of payment (how the customer paid: cash, bank transfer, card; the FormaPago key) for a Stripe payment method with no equivalent in the SAT catalog of forms of payment.
Invoice automatically	Whether the invoice is issued as soon as the payment is confirmed. See automatic invoicing.
Email invoices to customers	Whether the customer receives their CFDI by email.
Request tax details by email	Whether a customer without tax details receives a link to upload their Constancia de Situación Fiscal (the SAT tax status certificate).
Send self-invoicing link	Whether a customer without tax details receives a link to your Auto CFDI invoicing portal. Requires the Auto CFDI invoicing add-on and uses 1 ticket credit (ticket: a sales receipt your customer can later turn into a CFDI) per link.

In SAT codes and taxes by product, you assign each Stripe product its SAT product or service key, its SAT unit key, and its tax profile. The issuer is shown as read-only: the owner changes it from your Fiscalapi dashboard.

Automatic invoicing

The Invoice automatically switch is on when you link the account: the app issues the invoice as soon as the payment is confirmed. With the checklist complete, the app confirms it with the message “All set. New payments will be invoiced automatically.”

To turn it off, switch it off and save your settings. Each new payment from a customer with tax details waits until you issue their invoice from the payment panel with Issue invoice. Payments without tax details still go into the global invoice.

What happens to each payment

The app invoices the payments you receive in Stripe, regardless of how they were collected: Stripe Checkout, Stripe Invoices, subscriptions, or any other payment. Each payment is invoiced as soon as it's confirmed, always with PUE as the payment method (whether the CFDI is paid in full when issued, PUE, or later or in installments, PPD; not how the customer pays). An open Stripe invoice doesn't generate a CFDI until it's paid, and a payment at OXXO or SPEI (Mexico's interbank electronic payment system) is invoiced when it's confirmed.

The payment's customer	What the app issues
Has complete tax details	An income invoice (type I, the regular sales invoice) in their name, as soon as the payment is confirmed.
Has no tax details	Nothing for now: the payment goes into the global invoice for its period.
Has no tax details, and auto-invoice is active	A ticket and a link for the customer to request their invoice in your portal. If they don't request it, the payment goes into the global invoice.
Foreign, with no RFC and a country other than Mexico	A CFDI to the foreign generic RFC XEXX010101000.

Each line item in the CFDI corresponds to a line of the payment, with the SAT keys of its product and the taxes you charged in Stripe. The CFDI total matches the payment total to the cent.

The app invoices payments in MXN, USD, and EUR. Payments in USD carry the FIX exchange rate that Banxico publishes; payments in EUR carry the FIX dollar rate multiplied by the euro equivalence that the DOF publishes. A payment in any other currency appears in Needs attention.

Customer tax details

Tax details for the recipient live in the Stripe Customer: the RFC as a tax ID of type mx_rfc, and the tax regime, CFDI use (how the recipient will use the CFDI for tax purposes), and postal code in its metadata. The legal name (as registered with the SAT) and the email come from the Customer fields. Without tax details, the payment goes into the global invoice.

Way	How
From the customer's panel in Stripe	Open the customer, open the app, and click Add tax details (or Edit tax details). Import from Constancia fills in the details from the Constancia de Situación Fiscal; the PDF doesn't leave your computer.
In Stripe Checkout	The Checkout session asks for the RFC, the legal name, and the three details that Stripe doesn't have, and the app saves them in the Customer. See tax details in Stripe Checkout.
By the customer	With Request tax details by email or with auto-invoice, the customer receives a link by email and enters their details on a Fiscalapi page.

When you save a customer's details, the app invoices their pending payments from the current month that aren't in a global invoice yet.

Income, credit note, and global invoice

Each payment from a customer with tax details generates an income invoice. Each refund or lost dispute on an invoiced payment generates a credit note (an Egreso CFDI), and payments without an invoice go into the global invoice for the period.

Global invoice

At the close of each period, the app issues the global invoice for the payments without an invoice, within the 24 hours after the close that the SAT requires. The period follows the time zone of the issuer's place of issue (the postal code where the CFDI is issued).

The app issues one global invoice per issuer and per currency, with recipient XAXX010101000 and one line item per payment, as the global invoice filling guide requires. If a payment from the current month is already in a global invoice and the customer later asks for their invoice, Invoice customer issues a credit note related to the global invoice, and then the customer's own invoice. It uses 2 stamps.

Refunds and disputes

The app issues the credit note for each refund, with the same issuer as the CFDI it relates to:

Case	What the app issues
Full or partial refund of a payment with an invoice	A credit note related to the invoice, for the refunded amount.
Refund of a payment included in a global invoice	A credit note related to the global invoice, with recipient XAXX010101000.
Refund of a payment that still has no invoice	Nothing: the payment is adjusted to the amount that wasn't refunded, or it's discarded.
Dispute closed as lost	The same as a full refund.
Refund made outside Stripe, such as one for an OXXO payment	You issue it yourself from the payment panel with Issue credit note.

A credit note never exceeds what remains to be refunded on the payment.

If a refund fails after it's applied, the payment panel flags it and offers Restore payment.

Invoice lifecycle

The app issues each CFDI on its own. You step in from the payment panel in the Stripe Dashboard to correct, credit, or resend. With Email invoices to customers turned on, the customer receives their invoice by email when it's issued.

The app has no action to cancel an invoice without replacing it. You do that in Fiscalapi, from the dashboard or with DELETE /api/v4/invoices. See CFDI cancellation.

Actions from the payment panel

Each payment's panel shows its status, its CFDI, its credit notes, and the actions that apply at that moment. Actions that use stamps or cancel a CFDI ask for confirmation:

Action	What it does
Issue invoice	Issues the payment's CFDI. Uses 1 stamp.
Correct invoice	Issues a new invoice with the corrected details and requests the cancellation of the previous one with cancellation reason 01 (one of the SAT keys 01 to 04). Uses 1 stamp.
Issue credit note	Issues a credit note for the amount you specify, up to what's still left to credit. Uses 1 stamp.
Invoice customer	Takes a payment from the current month out of the global invoice when its customer asked for an invoice. Uses 2 stamps.
Restore payment	Restores a payment whose refund or dispute no longer applies. If it had a credit note, the app requests its cancellation with the SAT after you confirm the action, and restores the payment when the SAT confirms it.
Mark as invoiced outside the app	The app stops invoicing the payment. Use it only if you already invoiced it in Fiscalapi.
Download PDF, Download XML	Downloads the CFDI.
Resend email	Sends the CFDI to the customer again.
Retry	Retries a payment that needs attention.

Needs attention

A payment that couldn't be invoiced appears in the Needs attention tab, with its reason and the next step. A stamping rejection doesn't deduct any stamps.

The app retries on its own when the cause is resolved: a lack of stamps, an inactive subscription, the FIX exchange rate that Banxico hasn't published yet, or stamping with no response.

The rest waits for an action, such as correcting the customer's tax details or assigning the SAT keys of a product. When you take that action, click Retry in the payment panel.

A global invoice that couldn't be issued appears in the summary, and it's marked in red when its 24-hour deadline is at risk.

Unlink or uninstall

When you unlink your Stripe account or uninstall the app, Fiscalapi issues the global invoices for the current period with the pending payments, because the global invoice is required, and it stops receiving payments from that account. The CFDIs already issued remain in your Fiscalapi tenant. If you reinstall the app and link your Stripe account again, the app invoices the payments confirmed from that point on.

End-to-end features

Feature	How it works
Income invoice	Automatic when the payment is confirmed, or with Issue invoice.
Global invoice	Automatic at the close of each period, per issuer and per currency.
Credit note	Automatic for a refund or lost dispute, or with Issue credit note.
Correction	Correct invoice issues the new one and requests the cancellation of the previous one.
Download and email	Download PDF, Download XML, and Resend email.
Errors	Needs attention with reason, next step, and Retry.

Related resources