Skip to content
/
Receipt Flow Overview

Cheqi routes receipt contents without reading them. The merchant encrypts the definitive receipt payload for the customer's devices, and those devices generate and store the final receipt locally.

Current flow

  1. POST /recipient/resolve matches the customer and returns one temporary recipient for every device owned by that customer.
  2. The merchant SDK serializes the definitive receipt payload locally and encrypts it independently for every returned device.
  3. POST /receipt/encrypted consumes the match and stores a durable encrypted generation job for each device.
  4. Each device fetches its assigned job, decrypts the merchant payload, joins it in memory with Cheqi's server-known party and routing context, and generates its own CHEQI receipt with the shared Rust engine.
  5. One leased owner device resolves any downstream company or client-application recipients. It generates only the document formats those recipients require, encrypts a complete document bundle for each recipient, and submits the ciphertext for delivery.
  6. The backend stores hashes and routes ciphertext. It never receives the plaintext receipt contents or generated documents.
Downstream RecipientOwner DeviceCheqi APIMerchant / POS SDKDownstream RecipientOwner DeviceCheqi APIMerchant / POS SDKPOST /recipient/resolvematchId + temporary device recipientsEncrypt ReceiptPayload separately per devicePOST /receipt/encrypted202 Accepted + cheqiReceiptIdOpaque APNs / FCM work hintFetch assigned encrypted generation jobDecrypt, generate, hash, and store locallyResolve downstream recipients under a leaseGenerate required formats and encrypt bundlesSubmit encrypted downstream deliveriesQueue / webhook ciphertextAcknowledge durable local completion
Downstream RecipientOwner DeviceCheqi APIMerchant / POS SDKDownstream RecipientOwner DeviceCheqi APIMerchant / POS SDKPOST /recipient/resolvematchId + temporary device recipientsEncrypt ReceiptPayload separately per devicePOST /receipt/encrypted202 Accepted + cheqiReceiptIdOpaque APNs / FCM work hintFetch assigned encrypted generation jobDecrypt, generate, hash, and store locallyResolve downstream recipients under a leaseGenerate required formats and encrypt bundlesSubmit encrypted downstream deliveriesQueue / webhook ciphertextAcknowledge durable local completion

Push delivery is an optimization, not the source of truth. Devices also fetch the durable queue during normal synchronization, so a missed, throttled, offline, or force-quit push is repaired when the app can run again. See Mobile Delivery.

Zero-knowledge boundary

The protected data is the receipt body: line items, totals, taxes, payment details, fiscal data, and other issuer-supplied contents describing what was bought.

Cheqi legitimately knows the routing metadata it needs to match and deliver a receipt, including the recipient and issuer identity and payment information used for matching. It returns that server-known context to an authenticated owner device. The device performs the plaintext join in memory; the backend does not.

The merchant sends the encrypted generation input, not a server-generated receipt template. There is no plaintext template-generation step in the normal digital route.

Temporary recipients and durable jobs

Recipient IDs returned by /recipient/resolve are opaque, match-scoped, and short-lived. Do not store them as customer identifiers or reuse them in a later transaction.

The matchId is single-use. After /receipt/encrypted accepts the submission, the returned cheqiReceiptId and the backend's opaque generation-job ID identify the durable work. Mobile processing does not depend on the original match still existing.

Multi-device processing

Every matched owner device receives its own independently encrypted generation request and creates its own local CHEQI receipt. One device completing its work does not suppress the owner's other devices.

Third-party fan-out is different: exactly one active device holds the distribution lease. That device generates any required UBL documents and encrypts the downstream bundles. Other owner devices still generate and keep their local CHEQI copy, but do not duplicate downstream delivery.

What the SDK handles

Use a high-level complete-receipt method where available. It should:

  • resolve the customer before encrypting
  • select the explicit deliveryRouteType
  • serialize the definitive receipt payload locally
  • create a fresh symmetric key and ciphertext for every matched device
  • submit exactly the device recipient set returned by the match
  • preserve the cheqiReceiptId and delivery result for your records

The Cheqi mobile apps handle queue retrieval, local generation, durable local storage, downstream fan-out, and acknowledgement.

Delivery routes

The download fallback is explicit and separate from the device-generated route:

  • DOWNLOAD_FALLBACK uses a client-encrypted download payload. The content key stays in the URL fragment, so the backend stores ciphertext it cannot decrypt.
  • routeFound: false means the healthy online flow must stop with customer-not-found. Do not bypass that result through the low-level download endpoint.

See Download Links for the offline and anonymous download-link rules.

Getting Started

Recipient Resolution