ZATCA Phase 2 (FATOORA) Integration: Cryptographic Stamps & Real-Time Clearance APIs

1. Understanding ZATCA Phase 2 (FATOORA)

Under the Saudi Arabian Zakat, Tax and Customs Authority (ZATCA) regulatory framework, enterprise software and ERP systems must seamlessly integrate with the FATOORA platform. Unlike Phase 1, which required standalone QR codes, Phase 2 mandates direct cryptographic clearance and reporting via secure REST APIs.

Non-compliance incurs steep statutory penalties and business interruption. At Aerovix, we engineer turn-key, automated ZATCA Phase 2 middleware that integrates natively with SAP, Oracle, NetSuite, Salesforce, and custom ERP software.

2. XML UBL 2.1 Schema & Business Rule Enforcement

Every invoice must be formatted strictly according to the Universal Business Language (UBL 2.1) XML standard and comply with over 150 validation rules specified in the ZATCA business dictionaries. Missing currency codes, incorrect VAT categorizations, or decimal precision errors cause immediate clearance rejections.

3. Cryptographic Pipeline: SHA-256 & ECDSA secp256k1

The signing process consists of strict cryptographic operations:

1. XML Canonicalization (C14N): Eliminating whitespace discrepancies to ensure bitwise reproducibility.
2. Invoice Hashing: Generating a SHA-256 digest of the canonicalized invoice body.
3. Digital Signature Generation: Signing the digest with an elliptic curve private key (ECDSA secp256k1) certified by the ZATCA Cryptographic Stamp Identifier (CSID).
4. QR Code Generation: Encoding the seller name, VAT number, timestamp, invoice total, VAT amount, invoice hash, digital signature, and public key into a Base64-encoded TLV (Tag-Length-Value) data stream.

// crypto/zatcaSigner.ts
import * as crypto from 'crypto';

export function generateInvoiceHash(canonicalXml: string): string {
  const hash = crypto.createHash('sha256');
  hash.update(canonicalXml, 'utf8');
  return hash.digest('base64');
}

export function signInvoiceDigest(hashBase64: string, privateKeyPem: string): string {
  const sign = crypto.createSign('SHA256');
  sign.update(Buffer.from(hashBase64, 'base64'));
  sign.end();
  const signature = sign.sign(privateKeyPem);
  return signature.toString('base64');
}

4. Immutable Hash Chaining & Previous Invoice Hashes (PIH)

To prevent retrospective ledger tampering, ZATCA requires an unbroken cryptographic hash chain. Each invoice XML must embed the Previous Invoice Hash (PIH) of the preceding invoice generated by that specific Cryptographic Stamp device. For the first invoice, a predefined Base64 seed hash (all zeroes) is used.

5. Real-Time Clearance (B2B) vs. Reporting (B2C)

6. Enterprise Fail-Safe Architecture

In high-throughput environments issuing tens of thousands of invoices daily, our architecture utilizes an idempotent, queue-driven pipeline built on AWS SQS and Redis BullMQ. If ZATCA's endpoints experience temporary latency spikes, invoices are safely buffered with automatic exponential backoff, preventing point-of-sale or ERP locks.

Faisal Al-Mutawa

Head of Solutions (GCC), Aerovix

Authoring mission-critical architecture frameworks and guiding global enterprise software transformations at Aerovix.