Receipt Flow Overview

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

    IdentificationDetails customer = IdentificationDetails.builder()
        .paymentType(PaymentType.CARD_PAYMENT)
        .cardDetails(CardDetails.builder()
            .paymentAccountReference("PAR123456789")  // From payment terminal
            .cardProvider(CardProvider.VISA)
            .build())
        .build();

IdentificationDetails customer = IdentificationDetails.builder()
    .paymentType(PaymentType.IBAN_PAYMENT)
    .iban("NL91ABNA0417164300")
    .build();

IdentificationDetails customer = IdentificationDetails.builder()
    .paymentType(PaymentType.CARD_PAYMENT)
    .cardDetails(CardDetails.builder()
        .paymentAccountReference("PAR123456789")
        .cardProvider(CardProvider.VISA)
        .build())
    .customerEmail("customer@example.com")  // Fallback if not found
    .build();

ReceiptTemplateRequest receipt = ReceiptTemplateRequest.builder()
    .documentNumber("INV-2024-001")
    .issueDate(Instant.now())
    .currency("EUR")
    .totalAmount(new BigDecimal("121.00"))
    .totalTaxAmount(new BigDecimal("21.00"))
    
    // Add products
    .addProduct(Product.builder()
        .name("Coffee")
        .quantity(2.0)
        .unitCode(UnitCode.ONE)
        .unitPrice("5.00")
        .subtotal("10.00")
        .total("12.10")
        .addTax(21.0, "VAT", "2.10")
        .build())
    
    // Add tax breakdown
    .addTax(Tax.builder()
        .rate(21.0)
        .type("VAT")
        .taxableAmount("10.00")
        .amount("2.10")
        .label("VAT 21%")
        .build())
    
    .build();

{
  "event": "RECEIPT_FINALIZED",
  "receiptId": "abc123",
  "finalHash": "a3f5d8c2e1b4...",
  "finalizedAt": "2026-01-26T20:05:23Z",
  "deviceId": "device-uuid"
}

import com.cheqi.sdk.CheqiSDK;
import com.cheqi.sdk.models.*;
import com.cheqi.sdk.receipt.ReceiptResult;

// Initialize SDK
CheqiSDK sdk = CheqiSDK.builder()
    .apiEndpoint(Environment.PRODUCTION)
    .apiKey(System.getenv("CHEQI_API_KEY"))
    .build();

// Process complete receipt (one call does everything)
ReceiptResult result = sdk.getReceiptService()
    .processCompleteReceipt(
        identificationDetails,  // Customer identification
        receiptRequest          // Receipt data
    );

// Check result
if (result.isSuccess()) {
    System.out.println("✅ Receipt delivered to " + result.getReceiptCount() + " devices");
} else if (result.isCustomerNotFound()) {
    System.out.println("⚠️ Customer not found - prompt for email");
} else {
    System.out.println("❌ Failed: " + result.getMessage());
}

IdentificationDetails customer = IdentificationDetails.builder()
    .paymentType(PaymentType.CARD_PAYMENT)
    .cardDetails(CardDetails.builder()
        .paymentAccountReference("PAR123456789")
        .cardProvider(CardProvider.VISA)
        .build())
    .customerEmail("customer@example.com")  // Include email
    .build();

ReceiptResult result = sdk.getReceiptService()
    .processCompleteReceipt(customer, receiptRequest);

if (result.isDeliveredViaEmail()) {
    System.out.println("📧 Receipt sent to: " + result.getEmailAddress());
}

// Merchant authorizes your app via OAuth flow
// You receive an access token with 'read_receipts' scope

POST /webhook/subscription
Authorization: Bearer {oauth_access_token}
Content-Type: application/json

{
  "name": "My Accounting System",
  "events": ["RECEIPT_CREATED", "RECEIPT_FINALIZED", "CREDIT_NOTE_CREATED"],
  "notificationUrl": "https://your-app.com/webhooks/cheqi"
}

{
  "event": "RECEIPT_CREATED",
  "companyId": "uuid",
  "receiptId": "abc123",
  "createdAt": "2026-01-26T20:00:00Z",
  "encryptedReceipt": {
    "encryptedReceipt": "base64...",
    "encryptedSymmetricKey": "base64...",
    "encryptedCustomerDetails": "base64...",
    "encryptedCustomerAesKey": "base64..."
  }
}

{
  "event": "RECEIPT_FINALIZED",
  "receiptId": "abc123",
  "finalHash": "a3f5d8c2e1b4f7a9...",
  "finalizedAt": "2026-01-26T20:05:23Z",
  "deviceId": "device-uuid"
}

{
  "id": "INV-001",
  "issueDate": "2026-01-26",
  "accountingSupplierParty": { /* merchant info */ },
  "accountingCustomerParty": null,  // Empty initially
  "legalMonetaryTotal": { /* totals */ },
  "purchaseReceiptLines": [ /* items */ ]
}

{
  "partyName": { "name": "John Doe" },
  "postalAddress": { /* address */ },
  "contact": { "electronicMail": "john@example.com" }
}

{
  "id": "INV-001",
  "issueDate": "2026-01-26",
  "accountingSupplierParty": { /* merchant info */ },
  "accountingCustomerParty": {  // Merged here
    "partyName": { "name": "John Doe" },
    "postalAddress": { /* address */ },
    "contact": { "electronicMail": "john@example.com" }
  },
  "legalMonetaryTotal": { /* totals */ },
  "purchaseReceiptLines": [ /* items */ ]
}

// 1. Decrypt both parts
String receiptJson = decryptReceipt(encryptedReceipt, yourPrivateKey);
String customerJson = decryptCustomerDetails(encryptedCustomerDetails, yourPrivateKey);

// 2. Parse JSON
JSONObject receipt = new JSONObject(receiptJson);
JSONObject customer = new JSONObject(customerJson);

// 3. Merge customer into receipt
receipt.put("accountingCustomerParty", customer);

// 4. Canonicalize using SDK's RFC8785 Canonicalizer
String canonicalJson = RFC8785Canonicalizer.canonicalize(receipt.toString());

// 5. Calculate SHA-256 hash
String calculatedHash = SHA256.hash(canonicalJson);

// 6. Verify against finalHash from webhook
if (calculatedHash.equals(finalHash)) {
    System.out.println("✅ Receipt verified!");
} else {
    System.out.println("❌ Hash mismatch - receipt may be tampered");
}

String signature = request.getHeader("X-Cheqi-Signature");
String payload = request.getBody();

// Verify signature
Mac hmac = Mac.getInstance("HmacSHA256");
SecretKeySpec key = new SecretKeySpec(webhookSecret.getBytes(), "HmacSHA256");
hmac.init(key);
String calculatedSignature = Base64.getEncoder().encodeToString(
    hmac.doFinal(payload.getBytes())
);

if (!signature.equals(calculatedSignature)) {
    throw new SecurityException("Invalid webhook signature");
}

Product.builder()
    .name("Product Name")           // Required
    .quantity(1.0)                  // Required
    .unitCode(UnitCode.ONE)         // Required (see unit codes)
    .unitPrice("10.00")             // Required
    .subtotal("10.00")              // Required (before tax)
    .total("12.10")                 // Required (after tax)
    .sku("SKU-123")                 // Optional
    .brand("Brand Name")            // Optional
    .addTax(21.0, "VAT", "2.10")   // Tax breakdown
    .build()

Tax.builder()
    .rate(21.0)                     // Tax percentage
    .type("VAT")                    // Tax type
    .taxableAmount("10.00")         // Amount before tax
    .amount("2.10")                 // Tax amount
    .label("VAT 21%")               // Display label
    .build()

// ✅ GOOD - Email fallback
IdentificationDetails.builder()
    .paymentType(PaymentType.CARD_PAYMENT)
    .cardDetails(...)
    .customerEmail("customer@example.com")
    .build();

// ✅ GOOD - Use PAR from terminal
.paymentAccountReference("PAR123456789")

// ❌ AVOID - Don't use card numbers
.cardNumber("4111111111111111")  // Not supported

BigDecimal subtotal = products.stream()
    .map(Product::getSubtotal)
    .reduce(BigDecimal.ZERO, BigDecimal::add);

BigDecimal taxTotal = products.stream()
    .map(Product::getTaxAmount)
    .reduce(BigDecimal.ZERO, BigDecimal::add);

BigDecimal total = subtotal.add(taxTotal);

assert total.equals(receiptRequest.getTotalAmount());

int maxRetries = 3;
for (int i = 0; i < maxRetries; i++) {
    try {
        ReceiptResult result = sdk.getReceiptService()
            .processCompleteReceipt(customer, receipt);
        
        if (result.isSuccess()) {
            break;
        }
    } catch (CheqiSDKException e) {
        if (i == maxRetries - 1) {
            // Log error and notify support
            logger.error("Failed to send receipt after {} retries", maxRetries, e);
        }
        Thread.sleep(1000 * (i + 1)); // Exponential backoff
    }
}