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:

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

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.

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.

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.

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.

• Supply jurisdiction data
• Open a country field mapping and example payload
• Create a receipt
• Understand UBL output