{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-group"]},"type":"markdown"},"seo":{"title":"Sending Receipts","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":"sending-receipts","__idx":0},"children":["Sending Receipts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the SDK-level complete-receipt flow where available. It coordinates the"," ","merchant side of the current digital route:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["resolve the customer and owner devices"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["inspect the explicit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deliveryRouteType"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["serialize the definitive receipt payload locally"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["encrypt that payload independently for every matched device"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["submit the complete device set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/receipt/encrypted"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The accepted submission becomes durable device work. Final CHEQI and UBL"," ","documents are generated later on owner devices, not by the backend."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-receipt-flow","__idx":1},"children":["Complete receipt flow"]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","data-title":"Java","header":{"title":"Java","controls":{"copy":{}}},"source":"ReceiptResult result = sdk.getReceiptService()\n    .issueReceipt(identificationDetails, receiptPayload);\n\nif (result.isAccepted()) {\n    System.out.println(result.getDeliveryRouteType());\n    System.out.println(result.getCheqiReceiptId());\n} else if (result.isEmailReceiptRequired()) {\n    // Generate and submit the email receipt explicitly.\n} else if (result.isDownloadEnvelopeRequired()) {\n    // Build a final ReceiptEnvelope and call completeDownloadFallback(...).\n}\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"JavaScript","header":{"title":"JavaScript","controls":{"copy":{}}},"source":"const result = await sdk.receiptService.issueReceipt(\n  identificationDetails,\n  receiptPayload\n);\n\nif (result.isAccepted()) {\n  console.log(result.deliveryRouteType);\n  console.log(result.cheqiReceiptId);\n} else if (result.isEmailReceiptRequired()) {\n  // Generate and submit the email receipt explicitly.\n} else if (result.isDownloadEnvelopeRequired()) {\n  // Build a final ReceiptEnvelope and call completeDownloadFallback(...).\n}\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both current SDKs accept a definitive ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptPayload"]},". For digital delivery,"," ","the SDK encrypts that input locally; it does not send it to a plaintext"," ","template-generation endpoint. A missing route is raised as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CUSTOMER_NOT_FOUND"]}," ","by the high-level method rather than returned as a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptResult"]}," state."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"low-level-encrypted-submission","__idx":2},"children":["Low-level encrypted submission"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you implement the low-level flow yourself, submit the match and one"," ","independently encrypted copy per matched device:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"matchId\": \"match_opaque\",\n  \"storeId\": \"4ce2f858-d57d-4fde-a7ce-2e93f165494b\",\n  \"deviceDeliveries\": [\n    {\n      \"deviceRecipientId\": \"rcpt_temporary_1\",\n      \"encryptedContent\": \"base64-aes-gcm-ciphertext\",\n      \"encryptedAesKey\": \"base64-wrapped-content-key\"\n    },\n    {\n      \"deviceRecipientId\": \"rcpt_temporary_2\",\n      \"encryptedContent\": \"base64-aes-gcm-ciphertext\",\n      \"encryptedAesKey\": \"base64-wrapped-content-key\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["storeId"]}," is optional. When present, it must identify a store directly owned by"," ","the company in the authenticated token. The authenticated company remains the"," ","legal issuer."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful request returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"cheqiReceiptId\": \"CHQ-20260802-143502-A1B2C3\",\n  \"matchId\": \"match_opaque\",\n  \"status\": \"PENDING\",\n  \"createdAt\": \"2026-08-02T14:35:02Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Acceptance means Cheqi durably queued the encrypted work. It does not mean a"," ","phone has generated or acknowledged the receipt yet."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"submission-rules","__idx":3},"children":["Submission rules"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["matchId"]}," as single-use, short-lived flow state."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit exactly the temporary device recipient IDs returned by that match."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Encrypt the same definitive payload independently with a fresh symmetric key"," ","for every device."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Preserve the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cheqiReceiptId"]},"; it identifies the durable receipt job"," ","after the match has been consumed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A retry with the same match and identical request is idempotent. A conflicting"," ","replay is rejected."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not put plaintext receipt contents, final CHEQI JSON, or UBL XML in the"," ","encrypted-submission request outside the device ciphertext."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"legal-issuer-and-store","__idx":4},"children":["Legal issuer and store"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Determine the legal issuer before recipient resolution and use the same"," ","company-bound access token through resolution and encrypted submission."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For company groups, obtain a delegated token for the company that legally made"," ","the sale. A parent-company token cannot select a child as issuer. The deprecated"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["childCompanyId"]}," field does not grant parent-to-child issuance."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/companies/structure"},"children":["Companies, Child Companies, and Stores"]}," for"," ","retail, group, and franchise mappings."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"delivery-routes","__idx":5},"children":["Delivery routes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deliveryRouteType"]},"; do not infer the route from recipient count."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DIGITAL"]},": encrypt the definitive payload for every matched owner device and"," ","submit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/receipt/encrypted"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DOWNLOAD_FALLBACK"]},": build and encrypt the download envelope locally, then use"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/receipt/download"]},". The response URL carries the content key only in its"," ","fragment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["routeFound: false"]},": stop with customer-not-found in the healthy online flow."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Download fallback does not return a Cheqi-held recipient key and does not go"," ","through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/receipt/encrypted"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/receipts/download-fallback"},"children":["Download Links"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"after-submission","__idx":6},"children":["After submission"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cheqi creates durable encrypted generation work for each assigned device and an"," ","outbox entry for its opaque push hint. A phone may process the job from that"," ","hint or during foreground catch-up sync. Only device generation,"," ","acknowledgement, and encrypted downstream delivery advance the durable job;"," ","provider acceptance of a push does not."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/receipts/mobile-delivery"},"children":["Mobile Delivery"]}," for APNs, FCM, notification"," ","permission, retry, and force-quit behavior."]}]},"headings":[{"value":"Sending Receipts","id":"sending-receipts","depth":1},{"value":"Complete receipt flow","id":"complete-receipt-flow","depth":2},{"value":"Low-level encrypted submission","id":"low-level-encrypted-submission","depth":2},{"value":"Submission rules","id":"submission-rules","depth":2},{"value":"Legal issuer and store","id":"legal-issuer-and-store","depth":2},{"value":"Delivery routes","id":"delivery-routes","depth":2},{"value":"After submission","id":"after-submission","depth":2}],"frontmatter":{"title":"Sending Receipts","description":"Match owner devices, encrypt the generation payload, and submit durable work","seo":{"title":"Sending Receipts"}},"lastModified":"2026-08-11T23:21:19.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/receipts/sending","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}