The problem
In Croatia, every retail sale to a private customer must be fiscalized. The sale is reported to the Tax Administration in real time, and the tax office returns a unique code (JIR) that is printed on the invoice. Since January 2026 this applies to every payment method, including PayPal.
But PayPal money lands in PayPal, not in the merchant's invoicing software. No invoice is created and nothing is reported. Merchants copy every PayPal payment by hand. Refunds need a cancellation document (storno), and those are easy to forget. Many small merchants simply don't offer PayPal anymore for that reason.
What it does
FiskalBridge is a connector between PayPal and the merchant's invoicing software. The first supported service is FIRA, a Croatian invoicing service that fiscalizes invoices.
- The merchant connects PayPal and FIRA once.
- A PayPal webhook reports each payment, refund or dispute.
- Every payment becomes an invoice: one-time payments, subscription renewals and paid PayPal invoices.
- Every refund, chargeback or lost dispute becomes a storno (full or partial).
- The dashboard shows each event, its status (Sending, Done), the invoice lines, and an AI-written explanation in English and Croatian.
- Anything uncertain waits in a review queue ("Needs your attention"). The merchant fixes it and approves it.
About the demo: the demo runs in the PayPal sandbox and in FIRA Testing mode. In Testing mode FIRA creates offers (PONUDA), not fiscal invoices. In live mode FIRA issues fiscal invoices with a JIR.
How it decides
- Rules decide what is needed: an invoice, a storno, or nothing.
- AI (Gemini, structured tool output only) turns messy PayPal item data into clean invoice lines. It picks Croatian VAT rates (25, 13 or 5 %, or 0 % for merchants outside the VAT system), matches partial refunds to the original lines, and flags cross-border or B2B cases. A deterministic mapper is the fallback.
- Code validates every document and checks totals to the cent before anything is sent. Invalid documents are never sent.
Safety
- FiskalBridge never moves money in normal use. The Refund and Simulate dispute buttons are sandbox-only testing tools.
- PayPal webhooks are authenticated by signature verification.
- Retries are idempotent, so one payment can't produce two invoices.
- Credentials are stored server-side only. The browser sees only the last 4 characters.
How it's built
- TanStack Start (React 19, Vite) on Cloudflare Workers
- Tailwind CSS and shadcn/ui
- Postgres with row-level security and realtime (Lovable Cloud / Supabase)
- PayPal REST APIs (Orders, Subscriptions, Webhooks, Refunds) and the PayPal JS SDK
- FIRA Webshop/ERP API
- Gemini via the Lovable AI gateway
- Vitest
- Built with Lovable
Testing it
No sign-up needed. Open the live demo view (read-only dashboard) and, in another tab, the test shop. Add a product and pay with the PayPal sandbox buyer account from the testing instructions, or choose "Debit or Credit Card" and use a PayPal sandbox test card. Within a few seconds the payment appears in the live view with the AI-prepared document, its explanation and the FIRA document number.
Challenges
- FIRA has no sandbox. Testing mode sends offers (PONUDA), which are not fiscalized, so the demo is safe.
- FIRA rejects any unknown field. The first end-to-end test failed on one extra field, so the payload is now built from a whitelist, with tests that fail if any other key appears.
- FIRA's duplicate-protection key is a number, but PayPal IDs contain letters. FiskalBridge keeps its own numeric ID and puts the PayPal ID in the order number.
- PayPal's simulated webhook events can't pass signature verification. They are accepted only in the sandbox, with a one-time code valid for 5 minutes.
- After the sandbox tools were separated from Testing mode, the public test shop could have created a real fiscal invoice for a merchant in Live mode. In Live mode the shop now works only for the signed-in owner.
- Judges can't sign up without a paid FIRA account, so there is a public, read-only live view with names and e-mails masked.
Accomplishments
- A full end-to-end run in the sandbox: a verified PayPal webhook, three clean invoice lines from the AI, validation passed, and FIRA accepted the document (an offer, in Testing mode).
- There is no bypass: an invalid document can't be sent.
- Built for non-technical merchants: setup is three steps, and technical details stay hidden behind buttons.
What's next for FiskalBridge
- One-click PayPal connection. Today the merchant copies a Client ID and Secret from the PayPal developer site. With PayPal partner status, merchants could connect by simply logging in to PayPal.
- Connectors for other invoicing software. Only FIRA is supported today.
Built With
- cloudflare-workers
- fira-api
- gemini
- lovable
- lovable-ai-gateway
- lovable-cloud
- paypal-js-sdk
- paypal-orders-api
- paypal-refunds-api
- paypal-rest-api
- paypal-subscriptions-api
- paypal-webhooks
- postgresql
- react
- shadcn-ui
- supabase
- tailwind-css
- tanstack-start
- vite
- vitest