11. Payments, fiscal and hardware

For: a builder whose customer asks for a payment method, a fiscal country or a device. Reference implementation: for the one thing a partner can build here today, an outside fiscal service's result on the sale, Shipping your own data in a manifest (the fiscal_readers kind) and chapter 7. Payments have no recipe: nothing in them is open to a partner yet. For hardware only A receipt laid out for your market applies.

The short answer

When to use it

Read this chapter when a quote includes money moving, a tax authority or a device. It tells you what to promise (very little, today) and the one door that is open: the fiscal reader.

Payments

What we provide. One payments core and one thin connector for each payment gateway, each connector passing our conformance kit.

A site takes one card connector at a time. That limit stays until it is lifted; a customer with two card providers on one site cannot have both.

Your own payment connector: decided, not specified or built. A builder will be able to write a payment connector that runs on the builder's own server and talks to our payments core through a published gateway contract: authorise, capture, void, refund, status and reconcile. It would be built in the builder's own editor, tested on a sandbox, pass our payments conformance kit, and run in one pilot store before going live. Card numbers would never pass in clear through our system or the builder's. The builder may sell it to its own customers, or through our marketplace once one exists. Not yet: its specification is still owed (chapter 9); a terminal wired to the counter, which needs a driver on the till device, comes in a second phase. Do not start building against it, and do not promise a date.

Your wallet on the tender screen: not covered yet. A customer's own wallet or loyalty scheme, spent at the till as its own payment method (the cashier taps it, sees the balance and what this sale may use, enters an amount), is specified and not released (chapter 9). What works today is the other half: earning on your side after the sale. Your service follows the event feed (chapter 5), reads the booked invoice and adds the customer's points in your own system. Spending them at the till does not work yet.

Fiscal and e-invoicing

The till never talks to a tax authority. A country's fiscal app, or an outside service, clears or reports each sale and records the result on the sale. The till reads the result and decides whether the receipt may print as a tax document.

• Our country apps are ours. Saudi Arabia and Mexico are read today. A new country's own app is ours to add.
• An outside fiscal service can record its result. If your service reaches the tax authority itself, a fiscal reader tells the till which fields on the sale hold your result and what each value means. It is live; a new country on this route needs no release of ours.

Steps: an outside fiscal service

1. The shop turns on Clearance required for its country. Without it the product refuses the reader: the receipts would print at once with no tax receipt number. This is done in the shop, before the install.
2. Your manifest declares the result fields and the reader (chapter 7, the fiscal_readers kind). The status, the tax receipt number and, if you have one, the QR are three different fields on the sale. Each is No Copy, allowed on submit, and at a permission level above 1 (never 0, never 1, never 9) that no other role may write. The map says what each value your service writes means, once each: cleared, reported or pending. Never not fiscal: that is the till's own classification, and it releases the receipt.
3. The shop switches the reader on, adds the role's sale rights and makes your service's key. The reader is installed switched off. The service's user holds one role, its own writer role, and nothing else. The installer gives that role rights only at the result fields' own level, so the shop adds the role's ordinary rights on the sale (read, write and submit) and generates the user's key (chapter 7 lists the steps).
4. Your service writes its result with its own key, by saving the submitted sale through the API with every result field filled, every time. A value counts only when the sale was last saved by one of the reader's declared writer users.
5. What the cashier sees. From the moment a sale for a company your service serves is booked, it waits as pending: "Waiting for the tax receipt number … ask the back office." A cleared or reported result releases the receipt.

To change fiscal service, let waiting sales clear first, then repoint the one reader.

The kit has tried this route only with a test script standing in for the fiscal service. No tax authority was reached.

What is refused, and why

• A result field anyone else can write. A field at permission level 0 (anyone who may edit a sale), at level 1 (the shop's Accounts Manager already writes there), at level 9 (the till keeps it for its own tax result), or one that is copied onto a new sale is refused when the reader is saved or switched on.
• A writer role held by anyone but the service's declared users. Refused, with the user named.
• A reader for a company whose country does not wait for clearance. Refused, naming the company.
• A status the map does not know. It writes nothing, and the sale keeps waiting.
• A value saved by anyone but a writer user. Never mirrored; the receipt keeps waiting.
• Another role gaining write on a result field later. The writer rule is checked again every time a value would be mirrored: if it no longer holds, nothing is mirrored and every receipt keeps waiting.
• More than one reader per source, or the same value twice in the map. Refused.
• A reader on a site with more than one company, unless every company's country waits for clearance. Our rule is one company per site.

Hardware

What we provide. Four ways to print: a network printer, the device's own print dialog, a helper app, and the counter printer on wired tills. Receipt formats and customer-display templates are configuration (chapter 4); a receipt laid out for your market is a recipe (A receipt laid out for your market).

Not covered yet. A QR code or fiscal mark on the receipt, a WhatsApp receipt, and labels printed from the till or Handheld are specified and not released (chapter 9). Labels today go through a desktop utility. A device driver stays ours: a builder cannot add one.

The kit has not yet run the counter printer or the helper app on real hardware.

When your service is down, and when the till is offline

• Your fiscal service is down: the sale waits pending and its receipt is held. A recorded pending stays until a result arrives, whatever the shop changes later; the service, or the back office, owes that sale its answer. The till promises no retry.
• The till is offline: cash goes on, and so does a card taken on the bank's own machine and recorded by hand. Split tender, gift card, store credit, on-account and loyalty wait for a connection. An integrated card, a tax receipt in a country that waits for clearance, live balances and live stock are refused. The sale itself is kept: once the till syncs it, it waits as pending like any other until your service answers. The kit has not rung a fiscal sale offline; this is how the product describes it.

Technical notes

What the kit has proven

• A fiscal reader installs, in order. On the test shop a manifest made the result fields, the role, its permission row and one integration user, then the reader, switched off. The shop's country had to wait for clearance first, or the reader was refused.
• The product held the writer rule. It refused to switch the reader on at permission level 1, without No Copy, and with its role held by someone else. Installed in order, it switched on, and a service's Queued, unknown and Accepted results showed on the sale as pending, unchanged and cleared (chapter 7).

What it has not

• A real fiscal service. The "service" in the test was the test's own script, saving the sale as the integration user; no tax authority was reached.
• A fiscal sale rung offline. The offline refusal and the pending wait after the sync (above) were read from the product's own documents, not run.
• Anything in payments. No partner connector, no wallet and no second card connector exist; nothing here was run.
• The print routes on real hardware: the counter printer and the helper app have not been run on real hardware.
• A site with a reader and a second company. Not run: the refusal is read from the product's code.

Sources

• Fiscal reader sources. The extension-point library's fiscal reader page (the POS app's development branch, 2026-10-07): the declaration, the writer rule, the refusal sentences, the pending behaviour and the offline note. The manifest side: ../recipes/manifest.md (fiscal_readers) and chapter 7. The kit's own walk of it is in chapter 7's what the kit has proven.
• Country apps. The two compiled-in readers (Saudi Arabia and Mexico) are read from the POS app's fiscal reader; a partner cannot add a compiled-in reader.
• Payments. One payments core, a connector per gateway and the conformance kit are from the payments workstream's own description; the partner connector's shape is the decision recorded for it, which has no specification yet and is not built. The one-card-connector-at-a-time rule is the core's: a second gateway-type payment method would switch off the card route.
• Offline. Cash, hand-recorded card, and the waits and refusals are the till's offline model; the pending after sync behaviour is the fiscal reader page's.
• Hardware. The four print routes are from the product's receipts and labels census; the counter printer goes through the hardware integration app and a print helper on wired tills.

See also

4. Configure first · 5. Outside apps and the event feed · 7. Manifests · 9. The extension points · 16. Possible, not possible, limits

This page in the kit