# Receipt Flow Overview

Cheqi’s current receipt flow has four stages:

1. Resolve the recipient from checkout data such as pairing code, card PAR, IBAN, email, or a prior `cheqiReceiptId`.
2. Generate a receipt template without customer personal data.
3. Build one plaintext recipient envelope per matched recipient by combining the receipt template with the server-generated customer context envelope, then encrypt that envelope using the recipient’s public key.
4. Deliver the encrypted payload to apps and other recipients. When no Cheqi recipient is found, fall back to PDF email delivery (when `recipientEmail` is available and email fallback is enabled) or to a self-service download link (when download fallback is enabled) for the issuing company or client application.


```mermaid
sequenceDiagram
    participant Merchant as Merchant / POS
    participant Cheqi as Cheqi API
    participant Recipient as Recipient Device / Client App / Webhook

    Merchant->>Cheqi: POST /recipient/resolve
    Cheqi-->>Merchant: matchId + matchedRecipients + buyerCountryCode + buyerType
    Merchant->>Cheqi: POST /receipt/template
    Cheqi-->>Merchant: Cheqi JSON + optional UBL PurchaseReceipt/Invoice XML + vatMetadata
    Merchant->>Merchant: Build recipient-specific envelopes
    Merchant->>Merchant: Encrypt envelope per recipient public key
    Merchant->>Cheqi: POST /receipt/encrypted
    Cheqi-->>Recipient: Deliver encrypted receipt
```

## What the SDKs do for you

All three current SDKs implement the same high-level orchestration:

- Run recipient matching first.
- Stop early when no recipient is found and PDF email fallback is not available.
- Derive accepted receipt formats from the matched recipients.
- Generate the receipt template only when delivery is possible.
- Enrich the template request with VAT context from the match response.
- Encrypt one payload per recipient.
- Submit the encrypted receipts with the `matchId` and computed `templateHash`.


## Matching behavior

`IdentificationDetails` currently supports these identifiers:

- `pairingCode`
- `cardDetails`
- `paymentAccountDetails`
- `recipientEmail`
- `cheqiReceiptId`


The matching services prioritize them in this order:

1. `cheqiReceiptId`
2. `pairingCode`
3. `paymentAccountDetails`
4. `cardDetails`
5. `recipientEmail`


Pairing code therefore overrides the other identifiers when present.

## Template generation behavior

The receipt template response can contain multiple representations:

- `cheqi`: Cheqi’s canonical JSON format
- `ublPurchaseReceipt`: UBL PurchaseReceipt XML
- `ublInvoice`: UBL Invoice XML
- `vatMetadata`: resolved VAT regime metadata


`buyerCountryCode`, `buyerType`, and `taxesApplied` should be treated as required receipt-template inputs. In practice, `buyerCountryCode` and `buyerType` come from recipient resolution, while `taxesApplied` comes from your transaction context.

## Envelope split before delivery

Before delivery, there are two separate plaintext objects in the process:

- `ReceiptEnvelope`: receipt content only
  - `cheqi`
  - `ublPurchaseReceipt`
  - `ublInvoice`
  - `vatMetaData`
- `ReceiptContextEnvelope`: customer context only
  - `xmlReceivingParty`
  - `receivingParty`
  - `paymentMeans`


The important distinction is:

- `encryptedReceipt` is the encrypted `ReceiptEnvelope`
- `encryptedCustomerDetails` is the encrypted `ReceiptContextEnvelope`


Recipients can advertise `acceptedFormats`. Those formats determine which receipt representations belong in the `ReceiptEnvelope`. The customer context envelope is derived separately from recipient resolution.

## Delivery outcomes

Current SDK result objects distinguish these outcomes:

- Digital delivery to matched recipients
- PDF email fallback when enabled
- Download fallback when enabled: the submission response includes a `downloadUrl` you present to the customer as a QR code or link
- Customer not found
- Failure


If no recipient is found, the flow uses the PDF email fallback when `recipientEmail` is present and email fallback is enabled for the company or client application. Otherwise, when download fallback is enabled, the match resolves to the [download fallback](/receipts/download-fallback) route: the flow continues as a normal encrypted submission, and the response carries a `downloadUrl` to a Cheqi-hosted receipt page where the customer can view the receipt and download the PDF. If neither fallback applies, the result is customer-not-found without generating a template.

## Recommended implementation path

- Use [Recipient Resolution](/receipts/recipient-resolution) to prepare `IdentificationDetails`.
- Use [Receipt Creation](/receipts/creation) to build the template request with transaction and VAT context.
- Use [Sending Receipts](/receipts/sending) for the end-to-end submission flow.
- Use [Download Fallback](/receipts/download-fallback) to offer self-service receipt downloads to unmatched or anonymous customers.
- Use the SDK pages for language-specific examples:
  - [Java SDK](/sdk/java)
  - [.NET SDK](/sdk/dotnet)
  - [Python SDK](/sdk/python)