{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Mobile Delivery","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":"mobile-delivery","__idx":0},"children":["Mobile Delivery"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cheqi uses push notifications as opaque work hints. The durable encrypted"," ","generation queue is the source of truth."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TD\n A[Encrypted generation job committed] --> B[Durable push outbox]\n B --> C[APNs or FCM work hint]\n C --> D[Targeted job fetch]\n D --> E[Decrypt and generate locally]\n E --> F[Persist local receipt]\n F --> G[Submit downstream ciphertext if elected]\n G --> H[Acknowledge device completion]\n C -. missed, delayed, or offline .-> I[Foreground queue sync]\n I --> D\n","diagramHtml":"

missed, delayed, or offline

Encrypted generation job committed

Durable push outbox

APNs or FCM work hint

Targeted job fetch

Decrypt and generate locally

Persist local receipt

Submit downstream ciphertext if elected

Acknowledge device completion

Foreground queue sync

","diagramHtmlDark":"

missed, delayed, or offline

Encrypted generation job committed

Durable push outbox

APNs or FCM work hint

Targeted job fetch

Decrypt and generate locally

Persist local receipt

Submit downstream ciphertext if elected

Acknowledge device completion

Foreground queue sync

"},"children":["flowchart TD\n A[Encrypted generation job committed] --> B[Durable push outbox]\n B --> C[APNs or FCM work hint]\n C --> D[Targeted job fetch]\n D --> E[Decrypt and generate locally]\n E --> F[Persist local receipt]\n F --> G[Submit downstream ciphertext if elected]\n G --> H[Acknowledge device completion]\n C -. missed, delayed, or offline .-> I[Foreground queue sync]\n I --> D\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"push-contract","__idx":1},"children":["Push contract"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Receipt and credit-note hints use this versioned payload:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"eventType\": \"RECEIPT_GENERATION_AVAILABLE\",\n \"eventVersion\": 1,\n \"jobId\": \"opaque UUID\",\n \"documentType\": \"RECEIPT\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["documentType"]}," may also be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_NOTE"]},". The payload contains no receipt line"," ","items, totals, encrypted generation body, generated document, customer payment"," ","identifier, or reusable recipient identifier."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On receipt, the app fetches only the assigned job using the opaque ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jobId"]}," and"," ","its authenticated device ID. Duplicate and out-of-order hints are safe because"," ","the server claim and local generation state are idempotent."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"durable-backend-behavior","__idx":2},"children":["Durable backend behavior"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The generation job and push-outbox rows are committed transactionally. A"," ","background dispatcher retries temporary APNs or FCM failures with exponential"," ","backoff. Multiple backend instances lock due rows so only one dispatcher sends"," ","a given outbox entry at a time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An invalid provider token permanently fails that device's outbox entry and is"," ","removed from active use. An APNs or FCM success only means the provider accepted"," ","the hint; it is not proof that the phone generated the receipt."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ios","__idx":3},"children":["iOS"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cheqi sends one APNs alert notification with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content-available: 1"]},", immediate"," ","priority, and push type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["alert"]},". The visible notification remains the primary"," ","delivery class, while ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content-available"]}," gives the containing app a"," ","best-effort background execution window for the targeted fetch."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cheqi does not send a second pure-silent notification for the same job. Silent"," ","background pushes are low priority, may be throttled, and would duplicate the"," ","same fetch without creating a delivery guarantee."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The iOS target must have:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the Push Notifications capability"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Background Modes enabled with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Remote notifications"]}," selected"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the correct APNs entitlement and environment for the installed build"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["APNs token registration is independent from permission to display alerts. The"," ","app registers for a device token at launch even when visible notifications are"," ","off. Cheqi explains the notification benefit once; it does not repeatedly show"," ","the system permission prompt. If permission is disabled, Profile shows a"," ","passive status and a link to the app's system settings."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["iOS background execution remains best-effort. The system may delay or end the"," ","window, and it normally does not relaunch the containing app after the user"," ","explicitly force-quits it. Opening or foregrounding Cheqi runs the authoritative"," ","queue sync and catches up missed work."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The existing Cheqi notification extension displays receipt notification"," ","content. It is not a Notification Service Extension and is not responsible for"," ","decrypting or storing generation jobs before the main app runs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"android","__idx":4},"children":["Android"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cheqi sends a high-priority FCM data message. A data message reaches"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FirebaseMessagingService.onMessageReceived"]}," while the app is backgrounded;"," ","using an FCM notification payload here would allow the system tray to bypass"," ","the app's processing code."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The service:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["validates the versioned work hint"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["posts the visible notification when Android allows it"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["enqueues one unique expedited WorkManager job for the generation-job ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["waits for network access"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["fetches and processes the assigned job through the existing idempotent"," ","receipt pipeline"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On Android 13 and later, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST_NOTIFICATIONS"]}," controls whether Cheqi can display"," ","the notification. It does not grant access to the durable receipt queue and is"," ","not the acknowledgement mechanism. Background execution can still be delayed"," ","by device battery policies, and FCM may deprioritize sustained high-priority"," ","traffic that does not result in user-visible notifications. Foreground sync is"," ","therefore still required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If FCM reports deleted messages, Cheqi schedules a full authoritative sync."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"notification-permission-behavior","__idx":5},"children":["Notification permission behavior"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Notifications matter because they make receipts timely and visible, but"," ","permission is not a data-delivery guarantee."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ask only after explaining the benefit in context."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Record that the explanation was shown so logout or device re-registration"," ","does not repeat it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep token registration active independently from visible-alert permission."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When permission is off, show a passive status and settings link instead of"," ","repeatedly prompting."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Always process the durable queue when the app becomes active."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reliability-guarantees","__idx":6},"children":["Reliability guarantees"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Push is a hint; the encrypted queue is authoritative."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Provider acceptance is not device completion."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Repeated hints and retries are safe."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each owner device independently generates and stores its own CHEQI receipt."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Exactly one leased device performs downstream fan-out."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Receipt contents remain encrypted until the assigned device decrypts them."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Foreground synchronization repairs missed, collapsed, throttled, offline, and"," ","force-quit delivery."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"production-verification","__idx":7},"children":["Production verification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before promoting this flow, test physical devices in the APNs/FCM environment"," ","used by the release build:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm the device token is registered after login and survives normal"," ","account reset/re-registration behavior."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Background the app without force-quitting it and submit an encrypted receipt."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm the outbox sends one hint and the device performs the targeted fetch."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm local generation, durable persistence, downstream delivery, and"," ","acknowledgement complete exactly once."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Repeat with visible notification permission disabled."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Repeat while offline, then restore connectivity and verify catch-up."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Force-quit iOS, submit a receipt, reopen Cheqi, and verify foreground sync"," ","catches it up."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test token rotation and an invalid-token response in the release provider"," ","environment."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not treat a successful backend ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]}," or an APNs/FCM acceptance log as the end"," ","of this test. The final evidence is the generated local receipt and completed"," ","durable job."]}]},"headings":[{"value":"Mobile Delivery","id":"mobile-delivery","depth":1},{"value":"Push contract","id":"push-contract","depth":2},{"value":"Durable backend behavior","id":"durable-backend-behavior","depth":2},{"value":"iOS","id":"ios","depth":2},{"value":"Android","id":"android","depth":2},{"value":"Notification permission behavior","id":"notification-permission-behavior","depth":2},{"value":"Reliability guarantees","id":"reliability-guarantees","depth":2},{"value":"Production verification","id":"production-verification","depth":2}],"frontmatter":{"title":"Mobile Delivery","description":"How iOS and Android wake, fetch, generate, and persist encrypted receipts","seo":{"title":"Mobile Delivery"}},"lastModified":"2026-08-02T21:39:49.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/receipts/mobile-delivery","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}