Skip to content
API Reference/
/
Submit encrypted credit n...

Cheqi API (v1)

Cheqi provides APIs for creating receipts and reading receipts for customers

Download OpenAPI description
api-docs.json
api-docs.yaml
Languages
Servers
Mock server
https://docs.cheqi.io/_mock/apis/api-docs
Generated server url
https://test.api.cheqi.io

Client Application Management

Endpoints for managing OAuth2 client applications, including registration, secret management, and public key configuration

Operations

Credit Note Management

Endpoints for creating, managing, and retrieving credit notes (refund receipts)

Operations

Generate credit note template

Request

Generates a UBL-compliant credit note template without customer personal data. The template can be used by the SDK to inject customer information and encrypt the credit note. Requires write_receipts OAuth scope.

Accessible for: Company, Client Application

Security
cheqi_oauth
Bodyapplication/jsonrequired
documentNumberstringrequired

This document number is a unique identifier provided by the seller, you use this number to uniquely identify this value in your system.

Example: "CREDIT-NOTE-123456"
originatorDocumentReferencestringrequired

This is the document number of the original receipt this credit note refers to.

Example: "RECEIPT-123456"
identifiersArray of objects(Identifier)

A list of identifiers for the receipt. For example order number, purchase order number, etc.

Example: "ORDER-123456, PURCHASE-ORDER-123456s"
issueDatestring(date-time)required

The date when the purchase receipt was issued.

Example: "2022-01-01T00:00:00Z"
currencystringrequired

The currency in which the purchase receipt is issued.

Example: "EUR, USD, GBP"
invoiceSubtotalnumberrequired

The subtotal of the invoice, calculated as the sum of all line items before any overall invoice-level adjustments or taxes. This amount represents the total value of goods or services listed on the invoice.

Example: 100
totalBeforeTaxnumberrequired

The total amount of the invoice excluding taxes, but including any overall discounts or charges. This amount may differ from the invoiceSubtotal if there are invoice-level adjustments.

Example: 100
totalTaxAmountnumberrequired

The total tax amount for the receipt. This should equal the sum of all tax amounts in the taxes list.

Example: 100
totalAmountnumberrequired

The total amount charged to the customer. Should equal totalBeforeTax + totalTaxAmount.

Example: 100
productsArray of objects(Product)required

The list of products included in the purchase receipt. Must contain at least one product.

products[].​namestringrequired

The product name

Example: "Product Name"
products[].​brandstringrequired

The brand name

Example: "Brand Name"
products[].​identifierstringrequired

The identifier or article number (merchant-defined)

Example: "123456"
products[].​descriptionstring

The description of the product

products[].​quantitynumber(double)required

The quantity of this item

Example: 20
products[].​baseQuantitynumber(double)

The base quantity of this item

Example: 20
products[].​unitCodestringrequired

The unit of measure code

Enum"C62""EA""KGM""GRM""MGM""TNE""LBR""ONZ""LTR""MLT"
Example: "C62"
products[].​periodobject(Period)
products[].​unitPricenumberrequired

The unit price of this item

Example: 10
products[].​discountsArray of objects(Discount)

The discounts applied to this line item

products[].​chargesArray of objects(Charge)

The extra charges applied to this line item

products[].​taxesArray of objects(Tax)required

The taxes applied to this line item

products[].​taxes[].​ratenumber(double)required

The tax rate as a percentage (e.g. 21.0 for 21%)

Example: 21
products[].​taxes[].​typestringrequired

The type of tax, e.g. "VAT", "GST", "Sales Tax"

Example: "VAT"
products[].​taxes[].​amountnumber

The calculated tax amount

Example: 10
products[].​taxes[].​taxableAmountnumberrequired

The total taxable amount for this tax rate

Example: 10
products[].​taxes[].​labelstring

The label of the tax

Example: "VAT 21%"
products[].​subtotalnumberrequired

The line subtotal, before tax. Typically: quantity * unitPrice - discounts + charges (net).

Example: 10
products[].​totalnumberrequired

The line total, after tax. Typically: subtotal + tax amounts (gross).

Example: 10
discountsArray of objects(Discount)

Overall discounts applied at the receipt level (not product-specific). Examples: "Loyalty discount", "Coupon code", "Volume discount"

chargesArray of objects(Charge)

Overall charges applied at the receipt level (not product-specific). Examples: "Delivery fee", "Administration free", "Services charge"

taxesArray of objects(Tax)required

Tax breakdown for the receipt. Each Tax entry represents a tax category applied to the receipt (e.g., VAT 21%, VAT 9%). The total tax amount is the sum of all tax amounts in this list.

taxes[].​ratenumber(double)required

The tax rate as a percentage (e.g. 21.0 for 21%)

Example: 21
taxes[].​typestringrequired

The type of tax, e.g. "VAT", "GST", "Sales Tax"

Example: "VAT"
taxes[].​amountnumber

The calculated tax amount

Example: 10
taxes[].​taxableAmountnumberrequired

The total taxable amount for this tax rate

Example: 10
taxes[].​labelstring

The label of the tax

Example: "VAT 21%"
notestring

A note that the seller wants to include on the credit note

curl -i -X POST \
  https://docs.cheqi.io/_mock/apis/api-docs/credit-note/template \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "documentNumber": "CREDIT-NOTE-123456",
    "originatorDocumentReference": "RECEIPT-123456",
    "identifiers": "ORDER-123456, PURCHASE-ORDER-123456s",
    "issueDate": "2022-01-01T00:00:00Z",
    "currency": "EUR, USD, GBP",
    "invoiceSubtotal": 100,
    "totalBeforeTax": 100,
    "totalTaxAmount": 100,
    "totalAmount": 100,
    "products": [
      {
        "name": "Product Name",
        "brand": "Brand Name",
        "identifier": "123456",
        "description": "string",
        "quantity": 20,
        "baseQuantity": 20,
        "unitCode": "C62",
        "period": {
          "startDate": "string",
          "startTime": "string",
          "endDate": "string",
          "endTime": "string",
          "durationMeasure": {
            "value": 0,
            "unitCode": "string",
            "unitCodeListVersionID": "string"
          },
          "descriptionCode": {
            "value": "string",
            "languageID": "string",
            "listAgencyID": "string",
            "listAgencyName": "string",
            "listID": "string",
            "listName": "string",
            "listSchemeURI": "string",
            "listURI": "string",
            "listVersionID": "string",
            "name": "string"
          },
          "description": "string"
        },
        "unitPrice": 10,
        "discounts": [
          {
            "amount": 5,
            "percentage": 20,
            "label": "Black Friday"
          }
        ],
        "charges": [
          {
            "amount": 5,
            "percentage": 3,
            "label": "Shipping"
          }
        ],
        "taxes": [
          {
            "rate": 21,
            "type": "VAT",
            "amount": 10,
            "taxableAmount": 10,
            "label": "VAT 21%"
          }
        ],
        "subtotal": 10,
        "total": 10
      }
    ],
    "discounts": [
      {
        "amount": 5,
        "percentage": 20,
        "label": "Black Friday"
      }
    ],
    "charges": [
      {
        "amount": 5,
        "percentage": 3,
        "label": "Shipping"
      }
    ],
    "taxes": [
      {
        "rate": 21,
        "type": "VAT",
        "amount": 10,
        "taxableAmount": 10,
        "label": "VAT 21%"
      }
    ],
    "note": "string"
  }'

Responses

Credit note template created successfully

Body*/*
idobject(Identifier)
issueDatestring
issueTimestring
documentCurrencyCodestring
notestring
creditNoteTypeCodeobject(Code)
accountingSupplierPartyobject(Party)
accountingCustomerPartyobject(Party)
legalMonetaryTotalobject(MonetaryTotal)
originatorDocumentReferenceArray of objects(DocumentReference)
creditNoteLineArray of objects(CreditNoteLine)
taxTotalArray of objects(TaxTotal)
verificationNoncestring

Submit encrypted credit note

Request

Submits an encrypted credit note to the queue for delivery to customer devices. The credit note is encrypted with customer device keys for end-to-end privacy.

Accessible for: Company, Client Application

Security
cheqi_oauth
Bodyapplication/jsonrequired
matchIdstringrequired

The match id that you received during customer matching

Example: "match_123456789"
parentCheqiReceiptIdstringrequired

The parent Cheqi this credit note refers to

Example: "CHQ-1234567-123456-123456"
encryptedCreditNotesArray of objects(EncryptedCreditNoteDto)uniquerequired

A set of encrypted credit notes

encryptedCreditNotes[].​recipientIdstring(uuid)required

The recipient ID of the credit note

encryptedCreditNotes[].​creditNoteIdstring

The credit note ID

Example: "UUID"
encryptedCreditNotes[].​originalReceiptIdstring

The original receipt ID

Example: "UUID"
encryptedCreditNotes[].​receiverTypestring

The receiver type of the credit note

Enum"WEBHOOK""DEVICE"
Example: "WEBHOOK/DEVICE"
encryptedCreditNotes[].​encryptedCreditNotestringrequired

The encrypted credit note

Example: "encryptedCreditNote"
encryptedCreditNotes[].​encryptedSymmetricKeystringrequired

Base64-encoded device-specific encrypted symmetric key

encryptedCreditNotes[].​encryptedCustomerDetailsstringrequired

Base64-encoded encrypted customer details.

encryptedCreditNotes[].​encryptedCustomerAesKeystringrequired

Base64-encoded encrypted customer details AES key

encryptedCreditNotes[].​finalHashstring
encryptedCreditNotes[].​publicKeystringrequired

Base64-encoded public key used to encrypt the request

encryptedCreditNotes[].​supplierPartyIdstring(uuid)required

Supplier party ID for storage

templateHashstringrequired

The hash of the credit note template

curl -i -X POST \
  https://docs.cheqi.io/_mock/apis/api-docs/credit-note/encrypted \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "matchId": "match_123456789",
    "parentCheqiReceiptId": "CHQ-1234567-123456-123456",
    "encryptedCreditNotes": [
      {
        "recipientId": "afdd332c-8290-47b9-aca2-368bf5f25a9d",
        "creditNoteId": "UUID",
        "originalReceiptId": "UUID",
        "receiverType": "WEBHOOK/DEVICE",
        "encryptedCreditNote": "encryptedCreditNote",
        "encryptedSymmetricKey": "string",
        "encryptedCustomerDetails": "string",
        "encryptedCustomerAesKey": "string",
        "finalHash": "string",
        "publicKey": "string",
        "supplierPartyId": "5079fce0-ff67-415d-875a-07499ab62d2b"
      }
    ],
    "templateHash": "string"
  }'

Responses

Encrypted credit note queued successfully

Body*/*
cheqiReceiptIdstring

The Cheqi receipt ID of the credit note

Example: "CHQ-CREDIT-12345678-123456-123456"
parentCheqiReceiptIdstring

The Cheqi receipt ID of the parent receipt

Example: "CHQ-12345678-123456-123456"
templateHashstring

The hash of the credit note template

Example: "9a39f25618892cc6d2ca6cd651af864543a34e7ee5b5c3efff6b0de3437a8383"
createdAtstring(date-time)

The timestamp of the credit note creation

Example: "1970-01-01T00:00:00Z"

Get all outstanding credit note initiation requests

Request

Retrieves all outstanding credit note initiation requests for the authenticated company or client application. These are customer-initiated refund requests that are pending processing.

Accessible for: Company, Client Application

Security
cheqi_oauth
curl -i -X GET \
  https://docs.cheqi.io/_mock/apis/api-docs/credit-note \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Credit notes retrieved successfully

Body*/*
recipientIdstring(uuid)required

The recipient ID of the credit note

creditNoteIdstring

The credit note ID

Example: "UUID"
originalReceiptIdstring

The original receipt ID

Example: "UUID"
receiverTypestring

The receiver type of the credit note

Enum"WEBHOOK""DEVICE"
Example: "WEBHOOK/DEVICE"
encryptedCreditNotestringrequired

The encrypted credit note

Example: "encryptedCreditNote"
encryptedSymmetricKeystringrequired

Base64-encoded device-specific encrypted symmetric key

encryptedCustomerDetailsstringrequired

Base64-encoded encrypted customer details.

encryptedCustomerAesKeystringrequired

Base64-encoded encrypted customer details AES key

finalHashstring
publicKeystringrequired

Base64-encoded public key used to encrypt the request

supplierPartyIdstring(uuid)required

Supplier party ID for storage

Get issuer public key

Request

Returns the issuer's public key for verifying the credit note signature. The device must be a valid recipient of this credit note to access the key.

Security
cheqi_oauth
Path
cheqiReceiptIdstringrequired

Cheqi receipt ID of the credit note

Headers
X-Device-IDstring(uuid)required

Device ID requesting the issuer key

curl -i -X GET \
  'https://docs.cheqi.io/_mock/apis/api-docs/credit-note/{cheqiReceiptId}/issuer-key' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'X-Device-ID: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Responses

Issuer public key retrieved successfully

Body*/*
publicKeystring
keyAlgorithmstring
Enum"RSA_2048""RSA_4096""ECDSA_P256""ECDSA_P384""ED25519"
keyCreatedAtstring(date-time)
issuerTypestring
issuerIdstring(uuid)

Recipient Management

Endpoints for resolving and matching receipt recipients

Operations

Receipt Management

Endpoints for creating and managing purchase receipts with end-to-end encryption

Operations

Webhook Management

Endpoints for managing webhook subscriptions to receive real-time event notifications

Operations