F1 — Portuguese VAT & EU OSS: what we need from you¶
Why this exists. Portugal Odyssey is the merchant of record for every booking. That means the customer pays us (Portugal Odyssey), we issue the invoice, we collect the VAT, and we remit it to Portugal's tax authority (Autoridade Tributária, "AT"). Stripe handles the payment; the tax compliance is on us. This brief lists exactly what you (or your accountant) need to provide so engineering can finish wiring the payment service before launch.
Status: Draft (2026-05-05). Ask 1, Ask 2, and Ask 3 below are independent — each can be answered separately and in any order. Engineering is not blocked on sandbox testing by any of these; we can keep building. They block going live with real customer money.
TL;DR — three asks, three owners¶
| # | Ask | Who | When |
|---|---|---|---|
| 1 | Confirm the company is VAT-active and share NIPC + NIF de IVA + registered address | You + accountant (TOC) | Anytime — earliest unblocks Stripe live business profile |
| 2 | For each service category we sell, tell us the PT VAT rate (23% / 13% / 6%) | You + accountant | Anytime — feeds Stripe Tax mapping; engineering can stub defaults until then |
| 3 | Pick a certified PT invoicing system (Moloni, InvoiceXpress, Vendus, Primavera, etc.) and share API credentials once chosen | You | Before live launch — Portugal requires a certified e-invoicing trail; Stripe receipts are not enough |
The accountant call also surfaces a fourth question (EU OSS yes/no) covered in §3 below, but that's a discussion topic, not a deliverable for you.
1. Ask 1 — Company VAT identity¶
We need the following so Stripe and the platform can address invoices correctly and remit VAT to AT in Portugal Odyssey's name.
What to send¶
- Legal company name (as registered at IRN / Conservatória)
- NIPC — 9-digit corporate tax number
- NIF de IVA — usually the same digits as NIPC, but only valid if the company is in the VAT-active regime (Regime Normal de IVA). Your accountant confirms this.
- Registered address (sede) — exactly as on the company papers
- Bank account (IBAN) — used by AT for VAT remittances
- Certified accountant (TOC) name + contact — they will be filing the quarterly Modelo 1 (Declaração Periódica do IVA) on the platform's behalf
If the company is not yet VAT-active¶
Your TOC files Modelo 1 — declaração de início de actividade with AT (~1-2 weeks). From the activation date forward, the company has quarterly VAT obligations even at zero turnover. Worth timing this with the launch window — activating too early means a few empty quarterly returns first.
What engineering does with it¶
- Configures the Stripe business profile (live mode) with the company name, NIPC, address
- Embeds the legal identity into the invoice template
- Sets up Stripe's automatic VAT computation against the PT registration
2. Ask 2 — VAT rate per service category¶
This is the most concrete deliverable and the easiest one to answer. We need a small spreadsheet that maps every type of service Portugal Odyssey sells to its Portuguese VAT rate.
Background — the three PT VAT rates relevant to tourism¶
| Rate | Typically applies to |
|---|---|
| 23% — taxa normal | Most professional services (tour guides, generic activities, platform commissions) |
| 13% — taxa intermédia | Restaurant meals, some hospitality services |
| 6% — taxa reduzida | Hotel accommodation (mainland), passenger transport in some regions |
Regional warning: Madeira and Azores have different reduced rates. If we'll sell Experiences in those regions, the TOC needs to flag it — Stripe Tax handles this, but only if we feed it the right
tax_codeper service.
What to send¶
A simple table (spreadsheet or markdown — whatever is easiest) with one row per service category we offer. Example:
| Service category | PT VAT rate |
|---|---|
| Guided walking tours | 23% |
| Wine-tasting experiences | 23% |
| Surf lessons | 23% |
| Restaurant meals (lunch / dinner included in Experience) | 13% |
| Hotel night (3-star+ in mainland) | 6% |
| Hotel night (Madeira) | (TOC confirms — likely different) |
| Inter-city transfer (mainland) | 6% (in some regions) / 23% (in others) |
| Platform booking fee | 23% |
This list does not need to be exhaustive on day one — start with the categories of partners we have today; we can extend as new categories onboard.
What engineering does with it¶
For each row, we attach a Stripe tax_code (Stripe's standardised tax category identifier) to the matching service in the partner-service catalog. Stripe Tax then computes the per-line VAT automatically at checkout, based on customer location.
3. Ask 3 — Certified PT invoicing system¶
This one is a decision, not an information request, and it has the longest lead time.
Why we can't just use Stripe receipts¶
Portugal mandates that B2C invoices for taxable supplies follow Decreto-Lei 28/2019 (the "factura" regime):
- Sequential, gap-free invoice numbering
- Specific format and field set (per-line VAT, total in EUR, seller details, optional buyer NIF, etc.)
- A certified invoicing software that the issuer is registered with at AT, OR direct integration with AT's e-invoicing endpoint
- Monthly SAFT-PT XML file submitted to AT as the audit trail
- Electronic invoicing mandatory for B2B above €1,000
Stripe issues a receipt, not a PT-compliant factura. The compliance bridge is a third-party invoicing system that is certified by AT.
Common picks (TOC will have an opinion)¶
| System | Why teams pick it | Notes |
|---|---|---|
| Moloni | Most popular SMB / marketplace tool in PT; good API; broad accountant familiarity | Probably the default safe pick |
| InvoiceXpress | API-first, developer-friendly, lightweight | Good if engineering integration is the priority |
| Vendus | POS-leaning; strong for hospitality/F&B-heavy operators | Heavier UI than InvoiceXpress |
| Primavera / SAGE / Holded / Pennylane | Full ERP — invoicing + accounting + payroll bundled | Pick if accounting integration (separate decision, F4) is in scope |
What we need from you¶
- Decision: which system? TOC's recommendation usually wins; engineering integrates with whatever they prefer.
- API credentials for that system (sandbox first, live before launch).
- Confirmation that the chosen system is certified by AT for the company's NIPC.
What engineering does with it¶
After Stripe's payment_intent.succeeded webhook fires, payment-service calls the chosen invoicing system's API to issue the factura under the platform's company. The invoice number, VAT breakdown, and PDF link flow back into the booking record and the customer's confirmation email.
4. The fourth question — EU OSS (One-Stop Shop)¶
This isn't a deliverable for you — it's a decision the accountant has to frame based on how Portugal Odyssey's revenue is structured. It matters because:
- If OSS applies, we register once in PT and one quarterly OSS return covers all EU cross-border sales — clean.
- If OSS doesn't apply (because the supplies are treated as place-of-supply = Portugal regardless of customer residence), we just file PT VAT quarterly and ignore OSS for now.
The discussion to have with the TOC¶
"Portugal Odyssey is the merchant of record for tourism Experiences delivered in Portugal. The customer can be from anywhere in the EU. Some Experiences include digital components (booking platform fee, AI itinerary generation). For VAT purposes: — What is the place of supply for the in-Portugal experience? PT, presumably. — What about the platform commission / booking fee component if billed separately? Could be OSS-eligible if treated as a digital service supplied cross-border. — Does the Union Scheme OSS registration help us, hurt us, or not apply?"
The TOC's answer changes how engineering itemises the invoice — but it doesn't change anything else in the build. We can ship Slices B–E without a definitive OSS answer; we just need it before live launch.
5. Out of scope for now (flag for later)¶
- Non-EU customers (UK post-Brexit, Switzerland, Norway, USA) — separate VAT registrations apply above respective thresholds. Defer until we see real cross-border non-EU traffic.
- B2B reverse-charge (when a partner is itself a VAT-registered entity in another EU country) — different invoice flag; affects the refund accounting work in Slice D.
- Accounting integration (Pennylane / Holded / Primavera) — separate decision (F4 in the plan); independent of invoicing system pick but easier if both are from the same vendor.
6. What is NOT blocked on any of this¶
- Engineering can ship Slices A, B, C, D, E of the payment plan against Stripe sandbox with no PT VAT setup at all. Sandbox = fake money + fake invoices.
- Cristina's catalogue work, partner onboarding, and Strapi content are all unaffected.
- The only thing this brief blocks is flipping live mode and accepting real customer payments in production.
7. How to send the answers¶
- Ask 1 (NIPC, NIF, etc.): paste into a reply or share a single text file. Sensitive but not secret — they're already on the company's VAT certificate.
- Ask 2 (VAT rates table): markdown, spreadsheet, or screenshot of TOC's reply — whatever is easiest.
- Ask 3 (invoicing system pick): name + a confirmation of "TOC says yes". API credentials when ready — do not paste credentials in chat; share via the engineer's secure channel (Bitwarden / 1Password share / encrypted file).
References¶
- Decreto-Lei 28/2019 — PT invoicing regime
- AT — Portal das Finanças, Balcão Único Regime UE (OSS portal)
- EU Directive 2017/2455 — VAT e-commerce package (OSS)
- Stripe Tax PT support: https://docs.stripe.com/tax/supported-countries/europe/portugal
- Plan #020 README —
docs/implementation-plans/020-payment-merchant-of-record/README.md, sections F1, F3, F4