How to Automate Stripe Invoicing in Portugal

To automate Stripe invoicing in Portugal, treat each settled payment as a signal, collect the fiscal data in Stripe, preserve the VAT information received, and create the FT or FR in TOConline or InvoiceXpress. Exceptions should remain in manual review, with a verifiable link between the payment and the invoice.

Which system handles each part of Stripe invoicing?

Stripe collects and records the payment. The invoicing system creates the Portuguese fiscal document. Between them, the integration validates the event, organises the data, and requests issuance from the selected provider. Confusing these roles can lead to filing a payment receipt as an invoice or duplicating documents when several events describe the same charge.

A Stripe confirmation does not automatically become a Portuguese invoice. The guide to Stripe invoices and receipts in Portugal explains the legal distinction. Here, the objective is to keep the transfer between the three systems predictable and auditable.

Which Stripe event should trigger invoice issuance?

The starting point should be a completed payment event, but the specific event depends on the flow. A one-off payment may arrive throughpayment_intent.succeeded. A paid subscription is handled through invoice.payment_succeeded. If the PaymentIntent is already attached to a Stripe invoice, processing both without a deduplication rule can create two attempts for the same sale.

The receiver must also validate the signature against the original webhook body. Stripe documentation warns that altering or serialising that body again prevents verification. After validation, an idempotency key identifies a repeat. For example, if Stripe resends the same event after a delayed response, the second delivery should finish without creating another invoice.

The webhook timestamp does not replace the fiscal rule for the issuance deadline. Article 36 of the Portuguese VAT Code generally requires issuance by the fifth working day after tax becomes chargeable and on the payment date in the cases specified there. The flow must retain the relevant transaction date, rather than relying only on when the server received the notification.

Which data must move from Stripe to the invoice?

The integration needs a coherent snapshot of the sale: payment reference, currency, total, lines, quantities, descriptions, customer, and the tax information supplied by Stripe. For subscriptions, that snapshot may come from the associated invoice; for a one-off payment, it may come from the PaymentIntent and its metadata. The selected source should be recorded so that the document can be explained later.

A missing VAT number or name must not be invented. Checkout can collect business tax identifiers in supported countries, but that mechanism does not resolve every consumer case. The guide to VAT numbers on invoices and in Stripe Checkout separates the fiscal obligation from the form's technical capability.

Consider a renewal with two lines, a clear description, the company's tax identifier, and tax calculated in Stripe. The invoice should retain both lines and their respective values. Combining everything into a generic line such as “services” loses useful information and makes the result harder to compare with the original charge.

How should VAT pass from Stripe to the provider?

The integration must not calculate, correct, or infer VAT rates. Stripe is the source of the tax rate, tax amount, inclusive or exclusive behaviour, and tax codes present in the sale. The integration's job is to carry those values across and apply the organisation's configured map to the code accepted by the provider.

A rate must not be selected from the country, postcode, or VAT number prefix. Those details may help explain a sale, but they do not replace the tax configuration in Stripe. The treatment of domestic, intra-EU, and non-EU transactions is covered in the guide to VAT on digital services sold through Stripe.

When Stripe supplies no tax data, the safe route is explicit. If the organisation has configured the appropriate default exemption code, the document can proceed at zero rate with that code. Without that setting, the payment must move to manual review. When a sale contains several tax rates, each line retains the tax data received from Stripe and uses the corresponding mapping. A missing or invalid mapping is one of the conditions that route the case to review.

How do you configure the automation step by step?

1. Map the current process. Identify who configures Stripe, who manages series in the invoicing application, and who resolves exceptions. A payment with nobody responsible for review is not automated; it is merely hidden in a queue.

2. Prepare the data in Stripe. Descriptions, lines, currency, customer identification, and tax configuration should be present before payment. Correcting them after issuance may require a corrective document.

3. Connect the Stripe account and invoicing provider through their supported authorisation mechanisms. Secrets and tokens should remain encrypted on the server, never in a shared file or a message sent to the team.

4. Select the provider, series, FT or FR type, and preference for a draft or final document. Draft availability depends on the provider's declared capabilities and the organisation's choice.

5. Configure the tax map without creating parallel geographic rules. Stripe values should point to provider codes; an absence or mismatch should have a known outcome, such as manual review.

6. Test distinct scenarios before activation: one-off payment, subscription, customer without a VAT number, zero rate, several tax rates, repeated event, provider outage, and refund. Each test should state the expected status and who owns the decision.

7. Activate the flow and monitor the first issuances. Reconciliation should compare Stripe IDs with provider IDs and numbers, rather than relying only on success messages.

How do you choose between FT, FR, draft, and final?

The supported flow works with FT and FR. The choice belongs to the organisation's configuration and accounting process, not to an inference from the payment method. A successful Stripe payment is treated as settled; the document state at the provider is a separate decision.

TOConline and InvoiceXpress use different authentication and API flows, although either can be part of the same process. The TOConline and InvoiceXpress comparison helps with a choice based on pricing, drafts, accountant access, and multi-company management.

What should happen when data is missing?

A predictable failure should produce a visible status, not an approximate invoice. Typical cases include a missing series, an unmapped tax code, insufficient country information for a zero-rate transaction, a VAT number rejected by the provider, or credentials that require new authentication. The record should state the reason and allow another attempt after correction.

For example, if Stripe supplies no tax and there is no default exemption code, the integration must not guess. The payment remains settled, but issuance stays in manual review. After the configuration is corrected, another attempt reuses the same transaction and avoids creating a second record for the charge.

Temporary provider outages can be retried within limits. A technical retry does not replace human judgment when the problem is fiscal or data is missing. Separating these cases prevents a queue from trying indefinitely to resolve something that requires configuration.

How should refunds and credit notes be handled?

A refund changes the financial status of the transaction, but it does not erase an invoice that has already been issued. Thecharge.refunded event can record whether the refund is partial or full. Issuing a credit note is a separate accounting process and must not be promised solely because the Stripe status changed.

For a partial subscription refund, retain the original value, refunded amount, associated invoice, and any corrective document created at the provider. Altering the original invoice to match the new balance destroys the audit trail. The procedure should be confirmed with accounting before this stage is automated.

How do you protect customer data during the integration?

A payment may contain the name, email address, VAT number, and address needed to create or locate the customer at the provider. Those details are needed in memory during processing, but they do not have to be duplicated in the integration database. Normalised per-organisation HMAC hashes and source-system IDs can be retained for search and matching.

Normalisation must be identical on write and read. If a VAT number is stored without spaces but searched with spaces, matching fails and may create a duplicate customer. For example, the same email address must be transformed in the same way before its HMAC is calculated on both paths.

Which check confirms that the automation works?

A useful test does not end with a successful HTTP response. It must prove that the event was accepted once, the transaction was linked to one invoice, and the provider returned the expected type, state, number, and total. It must also show that an incomplete case stops for review without creating an incorrect fiscal document.

A small sample can include a one-off payment, a subscription renewal, and a repeated event. Compare the total and tax received from Stripe with the document lines, confirm the series, and verify that the repeat did not create another invoice. The document requirements can be reviewed in the guide to Portuguese invoice requirements.

The same discipline continues in production: payments without a document, open manual reviews, and total differences should appear in an operational queue. Automation means reducing repetitive work without hiding fiscal decisions, exceptions, or reconciliation failures.