# Credit Notes

Credit notes enable merchants to process returns and refunds for previously issued receipts. Customers initiate return requests through the Cheqi app, and merchants respond by issuing credit notes.

## Overview

The credit note flow in Cheqi:

1. **Customer initiates** - Customer requests a return through the Cheqi app
2. **Merchant receives** - Encrypted return request delivered via webhook or API
3. **Merchant processes** - Merchant reviews, validates, and issues credit note
4. **Customer receives** - Credit note delivered to customer's app (linked to the original receipt)


All communication uses end-to-end encryption. Credit notes are always linked to their parent receipt via `parentCheqiReceiptId`.

Refund Responsibility
**Important:** Cheqi delivers credit notes to customers. Actual monetary refunds are handled by the merchant's own payment system. Cheqi does not process or transfer funds.

Prerequisite: a registered encryption key
Receiving and decrypting returns requires a registered public key — your **company** encryption key (API-key integrations) or your **client-application** key (OAuth integrations). Return requests are encrypted to that key, and you decrypt them with the matching private key. See [Generate and Upload a Public Key](/sandbox/getting-started#4-generate-and-upload-a-public-key).

The structured return flow is optional
You don't have to use Cheqi's encrypted return flow. If you'd rather handle returns entirely in your own system, embed a return code as a **QR code or barcode** on the receipt — at the receipt level or on individual product lines — and process returns however you like. Cheqi supports [embedded barcodes and QR codes](/receipts/creation) on receipts. In that case you don't need the encrypted return flow or an encryption key for returns.

## Credit Note Flow

```mermaid
sequenceDiagram
    participant Customer as Customer (Cheqi App)
    participant Cheqi as Cheqi API
    participant Merchant as Merchant System
    
    Customer->>Cheqi: 1. Initiate return request
    Cheqi->>Cheqi: 2. Encrypt return request
    Cheqi->>Merchant: 3. Send webhook<br/>(encrypted return request)
    Merchant->>Merchant: 4. Decrypt & validate request
    Merchant->>Merchant: 5. Process return<br/>(review items, refund)
    Merchant->>Cheqi: 6. Issue credit note<br/>(via API)
    Cheqi->>Cheqi: 7. Generate dual format<br/>(CheqiCreditNote JSON + UBL XML)
    Cheqi->>Cheqi: 8. Encrypt credit note
    Cheqi->>Customer: 9. Deliver credit note<br/>(documentType: CREDIT_NOTE)
    Customer->>Customer: 10. Decrypt & verify hash
    Customer->>Cheqi: 11. Submit final hash
    Note over Customer,Merchant: All communication uses<br/>end-to-end encryption
```

## Dual Format Delivery

Credit notes, like receipts, are delivered in **two formats simultaneously**:

| Format | Description | Use Case |
|  --- | --- | --- |
| **Cheqi JSON** (`CheqiCreditNote`) | Canonical JSON format optimized for apps | Display in Cheqi app, hash verification |
| **UBL XML** | Universal Business Language XML | Regulatory compliance, accounting systems |


Both formats are included in the encrypted envelope delivered to customer devices and webhook recipients. The Cheqi JSON format is used for integrity verification (RFC 8785 canonicalization + SHA-256 hashing).

## CheqiCreditNote Data Model

The `CheqiCreditNote` is the canonical JSON representation of a credit note. It mirrors the `CheqiReceipt` model but includes credit-note-specific fields.

### Fields

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `cheqiCreditNoteId` | String | Yes | Unique Cheqi identifier for this credit note |
| `documentNumber` | String | Yes | Your credit note number (e.g., "CN-2024-001") |
| `originatorDocumentReference` | String | Yes | Document number of the original receipt |
| `identifiers` | Array | No | Additional identifiers (order ref, transaction number) |
| `issueDate` | ISO 8601 | Yes | When the credit note was issued |
| `currency` | String | Yes | ISO 4217 currency code (e.g., "EUR") |
| `creditNoteSubtotal` | Decimal | Yes | Sum of all line items before adjustments |
| `totalBeforeTax` | Decimal | Yes | Total excluding taxes |
| `totalTaxAmount` | Decimal | Yes | Total tax amount |
| `totalAmount` | Decimal | Yes | Final total including tax |
| `products` | Array | Yes | Line items (minimum 1) |
| `discounts` | Array | No | Credit-note-level discounts |
| `charges` | Array | No | Credit-note-level charges |
| `taxes` | Array | Yes | Tax breakdown by rate/category |
| `period` | Object | No | Billing/service period |
| `note` | String | No | Seller's note on the credit note |
| `sellingParty` | Object | Yes | Merchant/seller information |
| `receivingParty` | Object | No | Customer/buyer information (encrypted separately) |
| `verificationNonce` | String | Yes | Unique nonce for hash verification |


### Example CheqiCreditNote JSON

```json
{
  "cheqiCreditNoteId": "CHQ-CN-20260211-143022-a1b2c3",
  "documentNumber": "CN-2024-001",
  "originatorDocumentReference": "INV-2024-001",
  "issueDate": "2026-02-11T14:30:22.000Z",
  "currency": "EUR",
  "creditNoteSubtotal": -100,
  "totalBeforeTax": -100,
  "totalTaxAmount": -21,
  "totalAmount": -121,
  "products": [
    {
      "name": "AirMax",
      "brandName": "Nike",
      "quantity": -1,
      "unitPrice": 100,
      "subtotal": -100,
      "total": -121,
      "taxes": [
        { "rate": 21, "type": "VAT", "amount": -21 }
      ]
    }
  ],
  "taxes": [
    { "rate": 21, "type": "VAT", "taxableAmount": -100, "amount": -21, "label": "VAT 21%" }
  ],
  "sellingParty": {
    "companyName": "Example Store",
    "companyLegalName": "Example Store B.V.",
    "taxNumber": "NL123456789B01",
    "address": {
      "street": "Keizersgracht 1",
      "city": "Amsterdam",
      "zipCode": "1015AA",
      "country": "NL"
    }
  },
  "note": "Refund for returned items",
  "verificationNonce": "a1b2c3d4e5f6..."
}
```

## Parent-Child Relationship

Every credit note is linked to its parent receipt through `parentCheqiReceiptId`. This field is **not part of the encrypted envelope** — it is provided as metadata in the delivery queue alongside the encrypted data.

| Field | Source | Description |
|  --- | --- | --- |
| `originatorDocumentReference` | Inside encrypted envelope | The **document number** of the original receipt (e.g., "INV-2024-001") |
| `parentCheqiReceiptId` | Queue metadata | The **Cheqi receipt ID** of the parent receipt (used for database lookups) |


This allows customer apps and webhook recipients to efficiently look up the original receipt and display credit notes as related documents.

## Credit Note Verification

Credit notes use the same verification flow as receipts:

1. **Canonicalize** the `CheqiCreditNote` JSON using RFC 8785
2. **Hash** the canonical JSON with SHA-256
3. **Submit** the hash to Cheqi backend
4. **Verify** against the stored hash via the verification API


See **[Receipt Verification](/verification/verification)** for the complete verification guide — the same process applies to credit notes.

## Next Steps

**Ready to implement credit notes?** Follow these guides in order:

### 1. Receiving Return Requests

Learn how to receive and decrypt customer return requests via webhooks or API polling.

→ **[Receiving Return Requests](/creditnote/receiving-returns)**

**What you'll learn:**

- Webhook setup and signature verification
- Polling endpoint for fetching outstanding requests
- Decrypting return request payloads
- Understanding RefundPreference and customer selections


### 2. Issuing Credit Notes

Learn how to build and issue credit notes in response to return requests.

→ **[Issuing Credit Notes](/creditnote/issuing-credit-notes)**

**What you'll learn:**

- Building credit note templates with negative amounts
- Mandatory fields and validation
- Issuing via API key or OAuth token
- Processing results and refund execution


## Additional Resources

- **[Java SDK Documentation](/sdk/java)** - Complete Java SDK reference
- **[.NET SDK Documentation](/sdk/dotnet)** - Complete .NET SDK reference
- **[Receipt Flow Overview](/receipts/overview)** - Learn about creating receipts
- **[Receipt Verification](/verification/verification)** - Verify receipt and credit note integrity