{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Receipt Creation","description":"Complete documentation for integrating Cheqi's digital receipt platform","keywords":["cheqi","digital receipts","api","sdk","java","javascript"],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"receipt-creation","__idx":0},"children":["Receipt Creation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Receipt creation begins with a definitive merchant-supplied ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptPayload"]},"."," ","This plaintext object exists only in merchant-controlled memory. The SDK"," ","serializes and encrypts it separately for each owner device returned by"," ","recipient resolution; Cheqi never receives it in plaintext."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The current Java and JavaScript SDKs expose this object as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptPayload"]},". In"," ","the digital flow it is an input to local encryption and on-device generation;"," ","it is not sent to a plaintext template endpoint."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"required-values","__idx":1},"children":["Required values"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The issuer supplies these values:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["documentNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issuer-assigned receipt number"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["issueDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date and time the issuer created the receipt"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 4217 currency code"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receiptSubtotal"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issuer-calculated subtotal"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalBeforeTax"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issuer-calculated total excluding tax"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalTaxAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issuer-calculated tax total"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issuer-calculated final amount"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["taxesApplied"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether taxes apply to this receipt"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["products"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Receipt line items"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK and mobile generator do not calculate fiscal totals, tax, signatures,"," ","sequences, or QR values for the issuer. Supply the legally definitive values"," ","from the POS or commerce system."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"optional-values","__idx":2},"children":["Optional values"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common optional fields include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifiers"]}," for issuer and transaction references"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discounts"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["charges"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["taxes"]}," for the receipt-level tax breakdown"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionDate"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchaseDate"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["period"]}," for billing or service periods"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["barcodes"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentDetails"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jurisdictionalData"]}," for country-specific fiscal and legal information"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The free receipt message is configured on the company in the Cheqi app. It is"," ","not supplied in each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptPayload"]},". The local engine uses that configured"," ","message for CHEQI ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["note"]}," and UBL ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:Note"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentDetails"]}," is the definitive issuer-supplied payment object. It remains"," ","inside the encrypted receipt payload. The owner device passes it unchanged to"," ","the local generator; server-known matching data does not replace or merge into"," ","it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"country-specific-receipts","__idx":3},"children":["Country-specific receipts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jurisdictionalData"]}," when your POS, fiscal device, or invoicing system has"," ","country-specific data that must remain attached to the receipt. This includes"," ","external regime identifiers, exact legal wording, fiscalization evidence,"," ","authority references, and namespaced extension fields."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cheqi preserves supplied country data but does not decide which local regime"," ","applies to a transaction or manufacture authority data. See"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/countries/overview"},"children":["Country Support"]}," for the supported country set and"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/countries/jurisdictional-data"},"children":["Supplying Jurisdiction Data"]}," for the"," ","request shape."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"plaintext-shape-before-encryption","__idx":4},"children":["Plaintext shape before encryption"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The exact schema is available as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptPayload"]}," in the API reference. A"," ","minimal illustrative payload looks like this:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"documentNumber\": \"INV-2026-001\",\n  \"issueDate\": \"2026-08-02T14:35:02Z\",\n  \"currency\": \"EUR\",\n  \"receiptSubtotal\": 10.00,\n  \"totalBeforeTax\": 10.00,\n  \"totalTaxAmount\": 2.10,\n  \"totalAmount\": 12.10,\n  \"taxesApplied\": true,\n  \"products\": [\n    {\n      \"name\": \"Coffee\",\n      \"identifier\": \"SKU-COFFEE-001\",\n      \"quantity\": 2,\n      \"unitCode\": \"C62\",\n      \"unitPrice\": 5.00,\n      \"subtotal\": 10.00,\n      \"total\": 12.10,\n      \"taxes\": [\n        {\n          \"rate\": 21.0,\n          \"type\": \"VAT\",\n          \"taxableAmount\": 10.00,\n          \"amount\": 2.10\n        }\n      ]\n    }\n  ],\n  \"taxes\": [\n    {\n      \"rate\": 21.0,\n      \"type\": \"VAT\",\n      \"taxableAmount\": 10.00,\n      \"amount\": 2.10,\n      \"label\": \"VAT 21%\"\n    }\n  ],\n  \"paymentDetails\": {\n    \"paymentMeansCode\": \"48\",\n    \"description\": \"Card\",\n    \"cardProvider\": \"VISA\",\n    \"cardLastFour\": \"4242\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example is plaintext for explanation only. Do not send this JSON directly"," ","to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/receipt/encrypted"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"per-device-encryption","__idx":5},"children":["Per-device encryption"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For every temporary owner-device recipient returned by"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /recipient/resolve"]},":"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["serialize the same definitive ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptPayload"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["generate a fresh AES-256 content key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["encrypt the serialized payload with AES-GCM"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["wrap that content key with the recipient's public key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["submit the recipient ID, ciphertext, and wrapped key as one"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deviceDeliveries"]}," entry"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not reuse a symmetric key across devices. Submit exactly one entry for every"," ","device returned by the match and no additional recipients."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"product-identifiers","__idx":6},"children":["Product identifiers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every product line requires an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifier"]},": the SKU, article number, or other"," ","issuer-controlled key for that line. Make it unique within the receipt."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["That identifier is also the durable key used in return flows. When a customer"," ","returns an item, it comes back as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lineItemId"]},", allowing the issuer to map"," ","the return to the original line. See"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/creditnote/receiving-returns#matching-returns-to-your-receipt-lines"},"children":["Receiving Return Requests"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-happens-on-the-phone","__idx":7},"children":["What happens on the phone"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After decryption, the owner device combines the merchant payload with the"," ","current supplier, customer, optional store, and routing context that Cheqi"," ","already knows. The shared Rust engine then generates and hashes the local CHEQI"," ","receipt."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The one device holding the downstream distribution lease also generates the UBL"," ","formats required by the resolved recipients. Those final documents are bundled"," ","and encrypted on the device. The backend receives ciphertext and hashes, not the"," ","plaintext CHEQI JSON or UBL XML."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Continue with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/receipts/sending"},"children":["Sending Receipts"]}," for the submission contract."]}]},"headings":[{"value":"Receipt Creation","id":"receipt-creation","depth":1},{"value":"Required values","id":"required-values","depth":2},{"value":"Optional values","id":"optional-values","depth":2},{"value":"Country-specific receipts","id":"country-specific-receipts","depth":2},{"value":"Plaintext shape before encryption","id":"plaintext-shape-before-encryption","depth":2},{"value":"Per-device encryption","id":"per-device-encryption","depth":2},{"value":"Product identifiers","id":"product-identifiers","depth":2},{"value":"What happens on the phone","id":"what-happens-on-the-phone","depth":2}],"frontmatter":{"title":"Receipt Creation","description":"Build the definitive receipt payload that is encrypted for owner devices","seo":{"title":"Receipt Creation"}},"lastModified":"2026-08-05T16:20:57.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/receipts/creation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}