Credit Notes

Credit notes let merchants document returns and refunds for previously issued receipts. A customer can submit an encrypted return request from the Cheqi app; the merchant validates it, handles the monetary refund, and issues a credit note linked to the original Cheqi receipt.

Refund responsibility

Cheqi delivers the credit note. Your payment system remains responsible for moving money.

The return-request flow is optional

You can handle returns entirely in your own system. For example, include a merchant-controlled barcode or QR code on the receipt or its product lines and use that identifier in your return process.

Flow

The customer submits a return request from the Cheqi app.
Cheqi routes the encrypted request to the original receipt issuer by webhook or polling.
The merchant decrypts the request, validates eligibility and quantities, and chooses an outcome.
The merchant processes the monetary refund and issues the definitive credit-note payload.
Cheqi queues the encrypted payload for the customer's owner devices, which generate the requested CHEQI JSON and UBL CreditNote documents.

The merchant submission links the new document to its parent using parentCheqiReceiptId. That value is delivery metadata; it is not a property of the generated CHEQI JSON document.

Customer return-request model

The decrypted CreditNoteInitiationRequest has these properties:

Property	Type	Required	Description
`cheqiReceiptId`	string	Yes	Cheqi identifier of the original receipt.
`receiptId`	string	Yes	Merchant-supplied identifier of the original receipt.
`customerNote`	string	No	Customer note, up to 1,000 characters.
`lineItems`	`ReturnLineItem[]`	Yes	At least one requested return line.
`refundPreference`	enum	Yes	`ORIGINAL_PAYMENT_METHOD`, `BANK_TRANSFER`, or `STORE_CREDIT`.
`refundBankAccount`	object	Conditional	Required only for `BANK_TRANSFER`; otherwise it must be absent.

Each ReturnLineItem contains:

Property	Type	Required	Description
`productId`	string	Yes	The merchant-supplied `identifier` of the original receipt product. Maximum 255 characters.
`quantity`	number	Yes	Requested return quantity; must be greater than zero.
`reasonCode`	enum	Yes	`DEFECTIVE`, `DAMAGED`, `WRONG_ITEM`, `NOT_AS_DESCRIBED`, `UNWANTED`, `EXPIRED`, or `INCOMPLETE`.
`reasonDescription`	string	No	Optional explanation, up to 1,000 characters.

RefundBankAccount contains required iban and accountHolder strings plus an optional bic.

See Receiving Return Requests for the encrypted polling and webhook shapes.

Merchant credit-note input

The encrypted issuance payload contains a creditNoteTemplateRequest and taxesApplied. Cheqi does not calculate these values; the merchant supplies the definitive amounts and tax data.

Property	Type	Required	Description
`documentNumber`	string	Yes	Merchant's unique credit-note number.
`originatorDocumentReference`	string	Yes	Merchant document number of the original receipt.
`identifiers`	object[]	No	Additional `{ type, value }` document identifiers.
`issueDate`	ISO 8601 date-time	Yes	Credit-note issue timestamp.
`currency`	string	Yes	ISO 4217 currency code.
`creditNoteSubtotal`	decimal	Yes	Sum of line amounts before document-level adjustments and tax.
`totalBeforeTax`	decimal	Yes	Total after document-level discounts and charges, excluding tax.
`totalTaxAmount`	decimal	Yes	Total tax amount.
`totalAmount`	decimal	Yes	Tax-inclusive credit amount.
`products`	product[]	Yes	At least one credited product; every product needs `name` and `identifier`.
`discounts`	discount[]	No	Document-level discounts.
`charges`	charge[]	No	Document-level charges.
`taxes`	tax[]	Conditional	Required when `taxesApplied` is `true`; may be empty otherwise.
`period`	object	No	Service or billing period.
`jurisdictionalData`	object	No	Country-specific fiscal and legal data.

Use positive quantities and credit amounts. The document type communicates that these values are credits; do not negate the lines or totals.

The legacy note input is accepted for compatibility but is not used to generate the document note. The generated note comes from the issuer's configured company receipt text.

Generated CHEQI JSON

Owner devices combine the merchant input with trusted company, store, recipient, and document context. The generated JSON contains:

Property	Required	Source
`documentNumber`	Yes	Merchant input.
`originatorDocumentReference`	Yes	Merchant input.
`identifiers`	No	Merchant input; omitted when empty.
`issueDate`	Yes	Merchant input.
`currency`	Yes	Merchant input.
`creditNoteSubtotal`	Yes	Merchant input.
`totalBeforeTax`	Yes	Merchant input.
`totalTaxAmount`	Yes	Merchant input.
`totalAmount`	Yes	Merchant input.
`products`	Yes	Merchant input.
`discounts`	No	Merchant input; omitted when empty.
`charges`	No	Merchant input; omitted when empty.
`taxes`	Yes	Merchant input; can be an empty array when tax does not apply.
`period`	No	Merchant input.
`note`	No	Issuer's configured company receipt text.
`sellingParty`	Yes	Trusted issuer context.
`store`	No	Trusted store context.
`receivingParty`	No	Resolved customer context.
`jurisdictionalData`	No	Merchant input.
`receiptUuid`	Yes	Device-generation context; also written as the UBL `cbc:UUID`.

cheqiCreditNoteId, parentCheqiReceiptId, and supplierPartyId are delivery or persistence metadata and are not properties of the generated CHEQI JSON document. verificationNonce is not part of the current model; use receiptUuid as the shared document identifier.

Formats and verification

The generated formats are:

CHEQI JSON, hashed after RFC 8785 canonicalization with SHA-256.
UBL CreditNote XML, hashed after exclusive XML canonicalization with SHA-256.

See UBL XML Credit Note Format and Receipt & Credit Note Verification.