Supplying Jurisdiction Data

jurisdictionalData is an optional top-level field of the merchant's plaintext ReceiptPayload. The SDK encrypts that payload independently for every matched owner device. Cheqi's backend stores and routes only the encrypted copies.

After decryption, the owner device combines the merchant payload with server-known supplier, customer, payment, and store context and invokes the Rust receipt engine locally.

{
  "jurisdictionalData": {
    "countryCode": "US",
    "additionalFields": [
      {
        "code": "US:REGION",
        "value": "CA"
      }
    ]
  }
}

Only add this object when the selected country/regime has information without a canonical receipt field. Merge it into the same ReceiptPayload that contains documentNumber, amounts, products, taxes, and other merchant-supplied receipt content.

Only after checking this table should you add a namespaced additionalFields[] value. For example, Portugal's ATCUD has no generic receipt field and therefore remains a Portuguese extension.

All example rates, amounts, identifiers, wording, and authority values are illustrative. They are not defaults and must not replace current values from your tax, POS, fiscal-device, or authority integration.

New integrations should always set countryCode. Supplier-country fallback exists for compatibility. If both are present, the explicit jurisdiction country takes precedence.

Legacy input names profile and profileVersion remain accepted for encrypted payloads created by older SDKs. New integrations must use regime and regimeVersion.

Use common slots whenever one exists:

Do not duplicate a common value under a country code. For example, put a register ID in fiscalization.cashRegisterId, not in a second DE:REGISTER_ID field.

Do not create a fiscalization object merely to say that the selected country regime is not fiscalized. Omit it when no external fiscal operation occurred. Use NOT_REQUIRED only when the status itself is meaningful data produced by the merchant's workflow.

For a receipt that depends on an external fiscal operation:

1. Complete the device/provider/authority operation.
2. Obtain its final evidence.
3. Set status to FISCALIZED.
4. Generate the receipt on the owner device.

Final receipt generation rejects PENDING and FAILED. FISCALIZED requires at least one of fiscalDocumentNumber, transactionId, authorityReference, verificationCode, or signature.

Use NOT_REQUIRED only when the merchant's own compliance logic has selected a flow that does not require external fiscalization.

The country pages define the authoritative extension codes. Examples:

PT:ATCUD
GR:MYDATA_MARK
US:REGION
CH:VAT_INCLUDED

Codes:

• use uppercase country namespaces;
• may contain A-Z, 0-9, _, -, ., and :;
• may be at most 64 characters;
• must be unique, case-insensitively, within their array.

Unknown future fields remain accepted, but integrations should reuse a documented code when it already represents the value.

QR and barcode payloads are top-level receipt fields:

{
  "barcodes": [
    {
      "type": "QR_CODE",
      "data": "exact-payload-produced-by-the-pos-or-authority",
      "label": "Fiscal verification"
    }
  ],
  "jurisdictionalData": {
    "countryCode": "DE",
    "regime": "DE_KASSENSICHV",
    "regimeVersion": "2026-07"
  }
}

The engine treats data as opaque. It preserves and references the payload but does not construct, sign, parse, or normalize it.

{
  "legalTexts": [
    {
      "code": "REVERSE_CHARGE_NOTICE",
      "text": "Exact wording supplied by the merchant system",
      "languageCode": "en-IE",
      "displayRole": "NOTICE"
    }
  ]
}

Use displayRole to tell a receiving or rendering application how the exact text is intended to appear:

The role is semantic: Cheqi preserves it but does not select the text, language, or position for the merchant. Do not translate or paraphrase required wording inside Cheqi.

legalTexts is not the merchant's free receipt message. That message is configured on the company in the Cheqi app and remains available as CHEQI note and UBL cbc:Note. Do not put it in the receipt payload.

The engine writes the legal text to ext:UBLExtensions in UBL PurchaseReceipt, Invoice, and CreditNote:

<ext:UBLExtensions>
  <ext:UBLExtension>
    <ext:ExtensionAgencyID>CHEQI</ext:ExtensionAgencyID>
    <ext:ExtensionVersionID>1</ext:ExtensionVersionID>
    <ext:ExtensionURI>urn:cheqi:ubl:extension:jurisdictional-legal-text:1</ext:ExtensionURI>
    <ext:ExtensionContent>
      <cheqi:JurisdictionalLegalTexts>
        <cheqi:LegalText
            code="REVERSE_CHARGE_NOTICE"
            displayRole="NOTICE"
            languageCode="en-IE">Exact wording supplied by the merchant system</cheqi:LegalText>
      </cheqi:JurisdictionalLegalTexts>
    </ext:ExtensionContent>
  </ext:UBLExtension>
</ext:UBLExtensions>

This deliberately does not use cbc:Note, so jurisdictional wording cannot overwrite or become confused with the company-configured receipt message.

Cheqi regime identifiers are not written to UBL cbc:ProfileID. That element is reserved for a genuine UBL customization/business-process profile and is not inferred from country receipt data.

Every owner device generates and stores its CHEQI document locally. Only the device holding the downstream distribution lease generates the formats currently accepted by third parties, encrypts one envelope per recipient, and submits ciphertext.

Generating a missing UBL document later is a wallet export fallback. It uses CHEQI JSON stored locally on the device; the backend does not store plaintext CHEQI JSON.

The same jurisdiction structure is available on credit-note payloads.

• Country capabilities and examples
• Country coverage and boundaries
• Receipt creation
• Credit notes