{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"UBL XML Receipt Format","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":"ubl-xml-receipt-format","__idx":0},"children":["UBL XML Receipt Format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a downstream recipient accepts ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UBL_PURCHASE_RECEIPT"]},", the elected owner"," ","device generates a serialized UBL 2.4 XML document. When a recipient accepts"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UBL_INVOICE"]},", that device can generate UBL Invoice XML instead or in addition."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The device includes only the accepted formats in that recipient's encrypted"," ","document bundle. Cheqi routes the ciphertext and final hashes; it does not"," ","receive the plaintext XML."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ubl"]}," field is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["string"]}," — parse it as XML to access the full receipt structure."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"purchasereceipt-schema","__idx":1},"children":["PurchaseReceipt schema"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The XML conforms to the following schema:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"openapi","header":{"controls":{"copy":{}}},"source":"definitionId: PurchaseReceipt\n","lang":"openapi"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-elements","__idx":2},"children":["Key elements"]},{"$$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":"Element"},"children":["Element"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Nullable"},"children":["Nullable"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique receipt identifier"]}]},{"$$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":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date of issue (YYYY-MM-DD)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["issueTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Time of issue (HH:MM:SS)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction or tax-point date supplied by the issuer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction or tax-point time"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchaseDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Purchase or delivery date supplied by the issuer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchaseTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Purchase or delivery time"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["documentCurrencyCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 4217 currency code (e.g. EUR)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["note"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Company-configured free receipt message"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountingSupplierParty"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Seller/merchant party details"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountingCustomerParty"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Buyer party details (B2B)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Completed payment metadata, including optional MID/TID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMeans"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment method information"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["taxTotals"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tax breakdown per rate"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legalMonetaryTotal"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Total amounts (tax-exclusive, tax-inclusive, payable)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchaseReceiptLines"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Line items with product, quantity, price, and tax details"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["verificationNonce"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Nonce used for receipt verification"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"xml-namespace","__idx":3},"children":["XML namespace"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The root element uses the UBL 2.4 namespace:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"urn:oasis:names:specification:ubl:schema:xsd:PurchaseReceipt-2\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When jurisdictional legal text is present, the root also declares the standard"," ","UBL extension namespace and Cheqi's extension namespace:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"xml","header":{"controls":{"copy":{}}},"source":"xmlns:ext=\"urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2\"\nxmlns:cheqi=\"urn:cheqi:ubl:extension:components:1\"\n","lang":"xml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example","__idx":4},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"xml","header":{"controls":{"copy":{}}},"source":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<PurchaseReceipt\n    xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:PurchaseReceipt-2\"\n    xmlns:cac=\"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2\"\n    xmlns:cbc=\"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2\">\n  <cbc:ID>INV-2026-001</cbc:ID>\n  <cbc:IssueDate>2026-03-20</cbc:IssueDate>\n  <cbc:Note>Thank you for shopping with us.</cbc:Note>\n  <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>\n  <cac:AccountingSupplierParty>\n    <!-- Party details -->\n  </cac:AccountingSupplierParty>\n  <cac:Payment>\n    <cbc:MerchantID>MID-123456</cbc:MerchantID>\n    <cbc:PaymentTerminalID>TID-987654</cbc:PaymentTerminalID>\n  </cac:Payment>\n  <cac:PaymentMeans>\n    <cbc:PaymentMeansCode listID=\"UN/ECE 4461\">48</cbc:PaymentMeansCode>\n    <cac:CardAccount>\n      <cbc:PrimaryAccountNumberID>4242</cbc:PrimaryAccountNumberID>\n      <cbc:NetworkID>VISA</cbc:NetworkID>\n    </cac:CardAccount>\n  </cac:PaymentMeans>\n  <cac:LegalMonetaryTotal>\n    <cbc:TaxExclusiveAmount currencyID=\"EUR\">10.00</cbc:TaxExclusiveAmount>\n    <cbc:TaxInclusiveAmount currencyID=\"EUR\">12.10</cbc:TaxInclusiveAmount>\n    <cbc:PayableAmount currencyID=\"EUR\">12.10</cbc:PayableAmount>\n  </cac:LegalMonetaryTotal>\n  <cac:PurchaseReceiptLine>\n    <cbc:ID>1</cbc:ID>\n    <cac:Item>\n      <cbc:Name>Coffee</cbc:Name>\n    </cac:Item>\n    <cac:Price>\n      <cbc:PriceAmount currencyID=\"EUR\">5.00</cbc:PriceAmount>\n    </cac:Price>\n  </cac:PurchaseReceiptLine>\n</PurchaseReceipt>\n","lang":"xml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"free-receipt-message-and-jurisdictional-text","__idx":5},"children":["Free receipt message and jurisdictional text"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The company configures its free receipt message in the Cheqi app. The local"," ","engine places that text in CHEQI ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["note"]}," and UBL ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:Note"]},". A merchant does not"," ","send it in each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptPayload"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Jurisdictional wording has a different purpose and never uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:Note"]},"."," ","Values supplied through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jurisdictionalData.legalTexts[]"]}," are preserved in"," ","CHEQI JSON and written to a structured extension in UBL PurchaseReceipt,"," ","Invoice, and CreditNote:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"xml","header":{"controls":{"copy":{}}},"source":"<ext:UBLExtensions>\n  <ext:UBLExtension>\n    <ext:ExtensionAgencyID>CHEQI</ext:ExtensionAgencyID>\n    <ext:ExtensionVersionID>1</ext:ExtensionVersionID>\n    <ext:ExtensionURI>urn:cheqi:ubl:extension:jurisdictional-legal-text:1</ext:ExtensionURI>\n    <ext:ExtensionContent>\n      <cheqi:JurisdictionalLegalTexts>\n        <cheqi:LegalText\n            code=\"BE:GKS_DOCUMENT_HEADING\"\n            displayRole=\"DOCUMENT_HEADING\"\n            languageCode=\"nl-BE\">BTW-KASTICKET</cheqi:LegalText>\n      </cheqi:JurisdictionalLegalTexts>\n    </ext:ExtensionContent>\n  </ext:UBLExtension>\n</ext:UBLExtensions>\n","lang":"xml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The extension URI and element shape are identical in UBL Invoice. A receiving"," ","application can use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["displayRole"]}," to render a heading, notice, or footer without"," ","interpreting general-purpose note text."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"merchant-and-payment-terminal-identifiers","__idx":6},"children":["Merchant and payment terminal identifiers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a card payment, recipient resolution can supply two optional payment"," ","metadata fields. They appear in the locally generated CHEQI JSON as:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"paymentMeans\": {\n    \"paymentMeansCode\": \"48\",\n    \"cardProvider\": \"VISA\",\n    \"cardLastFour\": \"4242\",\n    \"merchantId\": \"MID-123456\",\n    \"paymentTerminalId\": \"TID-987654\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Rust engine maps those fields natively in UBL 2.4 PurchaseReceipt:"]},{"$$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":"CHEQI JSON"},"children":["CHEQI JSON"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"PurchaseReceipt"},"children":["PurchaseReceipt"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMeans.merchantId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:Payment/cbc:MerchantID"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMeans.paymentTerminalId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:Payment/cbc:PaymentTerminalID"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both values are optional. They are receipt metadata only and are never used to"," ","match a customer. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentTerminalId"]}," is the card-payment terminal identifier;"," ","it is not a fiscal cash-register, fiscal-device, or jurisdictional terminal"," ","identifier."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cheqi currently applies this native mapping to UBL PurchaseReceipt only. Do not"," ","assume that the same elements are present in UBL Invoice."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related","__idx":7},"children":["Related"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/receipts/creation"},"children":["Receipt Creation"]}," — how to build the encrypted generation input"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/receipts/overview"},"children":["Receipt Flow Overview"]}," — full receipt lifecycle"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/verification/verification"},"children":["Receipt Verification"]}," — verifying receipt integrity"]}]}]},"headings":[{"value":"UBL XML Receipt Format","id":"ubl-xml-receipt-format","depth":1},{"value":"PurchaseReceipt schema","id":"purchasereceipt-schema","depth":2},{"value":"Key elements","id":"key-elements","depth":2},{"value":"XML namespace","id":"xml-namespace","depth":2},{"value":"Example","id":"example","depth":2},{"value":"Free receipt message and jurisdictional text","id":"free-receipt-message-and-jurisdictional-text","depth":2},{"value":"Merchant and payment terminal identifiers","id":"merchant-and-payment-terminal-identifiers","depth":2},{"value":"Related","id":"related","depth":2}],"frontmatter":{"title":"UBL XML Receipt Format","description":"Structure of the UBL 2.4 PurchaseReceipt XML generated on the elected owner device","seo":{"title":"UBL XML Receipt Format"}},"lastModified":"2026-08-03T03:31:14.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/receipts/ubl-format","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}