# Country Support

Cheqi can preserve and render country-specific receipt information supplied by
your POS, fiscal device, or invoicing system. The current receipt engine accepts
these canonical issuance countries:

| Region | Countries |
|  --- | --- |
| European Union | Austria (`AT`), Belgium (`BE`), Germany (`DE`), Denmark (`DK`), Estonia (`EE`), Spain (`ES`), Finland (`FI`), France (`FR`), Greece (`GR`), Ireland (`IE`), Italy (`IT`), Netherlands (`NL`), Poland (`PL`), Portugal (`PT`), Sweden (`SE`) |
| Other Europe | Switzerland (`CH`), United Kingdom (`GB`), Iceland (`IS`), Norway (`NO`) |
| North America | Canada (`CA`), United States (`US`) |


`GB` is the canonical United Kingdom country code. `UK` is accepted as an input
alias and is normalized to `GB`.

Capability is not legal certification
Country support means the engine can create a receipt containing the supplied
local fields. It does not mean Cheqi decides which rules apply, certifies the
receipt as legally sufficient, or replaces a fiscal device, certified cash
register, tax authority, Peppol validator, or local professional review.

## How country data flows

Country-specific data is part of the merchant's plaintext
`ReceiptPayload.jurisdictionalData`:

1. Your POS determines whether the receipt needs country data that has no
canonical field. If it does, select the applicable external regime and
complete any required authority, fiscal-device, or certified-software
operation.
2. Your integration adds the returned identifiers, signatures, URLs, legal
text, and top-level barcode payloads to the `ReceiptPayload`.
3. The merchant SDK encrypts that payload independently for every matched owner
device.
4. Each owner device decrypts its copy and runs the shared Rust engine locally
to generate and store its CHEQI receipt.
5. Exactly one leased owner device also generates the formats accepted by
downstream third parties, encrypts one envelope per recipient, and submits
only ciphertext and delivery metadata.


The backend knows routing metadata such as the merchant, recipient, and payment
means, but it never receives or assembles plaintext receipt contents, CHEQI
JSON, or UBL documents in this flow.

## What the engine does

The engine:

- accepts optional country extensions and external-regime metadata;
- uses canonical receipt, party, payment, tax, identifier, and date fields
before considering country extensions;
- preserves legal text and arbitrary country-namespaced fields;
- preserves POS- or authority-produced fiscal evidence;
- includes country data in canonical CHEQI JSON and document hashes;
- maps regimes, legal text, fiscal evidence, and extension fields to explicit
UBL document references;
- can generate a missing UBL export from CHEQI JSON stored locally in a wallet;
- keeps non-VAT tax schemes such as `GST`, `QST`, and `SALES_TAX` distinct;
- rejects only structurally unsafe final states, such as `PENDING` or `FAILED`
fiscalization.


The engine does not:

- determine the applicable country, state, province, tax rate, threshold, or
exemption;
- calculate or verify government signatures, hashes, QR payloads, or authority
references;
- report transactions to tax authorities;
- infer whether a simplified invoice, full invoice, or fiscal receipt is
required;
- enforce country-specific legal completeness.


## Capability-test coverage

The engine's executable capability suite covers:

- all 21 canonical countries;
- all currently documented external regimes plus ordinary receipts that need
no jurisdiction data;
- cash, card, bank-transfer, and IBAN direct-debit examples;
- ordinary, fiscalized, correction, return, and credit-note examples;
- all 50 US states and the District of Columbia;
- deterministic CHEQI, UBL PurchaseReceipt, UBL Invoice, and UBL CreditNote
generation;
- wallet-side UBL export generation from locally stored CHEQI JSON.


These tests prove that the required information can be represented and
preserved. They deliberately do not enforce local rules or claim legal
compliance.

## Country selection

When `jurisdictionalData` is needed, new integrations should set its
`countryCode` explicitly. The supplier-country fallback remains available for
compatibility:

1. An explicit `jurisdictionalData.countryCode` takes precedence.
2. Otherwise, the engine uses `supplier.address.countryIsoCode`.
3. If neither exists, the engine does not invent a country.


Use the issuance jurisdiction selected by your own transaction and compliance
logic. Do not use the buyer's country automatically unless that is the correct
issuance jurisdiction for the transaction.

The engine does not determine whether an external regime applies. Keep the
country, selected regime, and legal supplier consistent in your integration.

## Next steps

- [Supply jurisdiction data](/countries/jurisdictional-data)
- [Open a country field mapping and example payload](/countries/profiles)
- [Create a receipt](/receipts/creation)
- [Understand UBL output](/receipts/ubl-format)