Skip to main content

🧾 ZATCA e-Invoicing (Phase 2)

BayanCore incorporates the ZATCA Fatoora Phase 2 (Integration Phase) mandate directly into the billing execution pipeline. Every invoice generated is structured, signed, and transmitted to ZATCA automatically in real-time.

1. Technical Requirements & Standards​

Compliant invoices must conform to the following standards:

  • XML Schema (UBL 2.1): Invoices are converted into a standardized XML format defined by the Universal Business Language (UBL 2.1) schema, containing specific Saudi tax extensions (such as tax category codes, buyer/seller CR numbers, and invoice type codes).
  • Base64 TLV QR Codes: A 2D barcode must be embedded in the PDF, containing the following Tag-Length-Value (TLV) encoded variables:
    1. Seller's Name (Tag 1)
    2. Seller's VAT Number (Tag 2)
    3. Invoice Timestamp (Tag 3)
    4. Invoice Total (Tag 4)
    5. VAT Total (Tag 5)
    6. XML Hash Signature (Tag 6)
    7. Public Key Certificate (Tag 7)
  • Hash Chaining: Every invoice contains a cryptographic hash of the preceding invoice's XML payload. This links invoices sequentially, preventing deletion or historical tampering.
  • PDF/A-3 Format: Invoices are delivered to buyers as a PDF/A-3 file, which visually renders the invoice while embedding the raw, signed XML document as an attachment.

2. Clearance vs. Reporting Flows​

The system splits transmission based on transaction types:

                  ┌───────── B2B Invoice ────────┐
                  ▼                              ▼
          [Guardian Validation]          [Guardian Validation]
                  │                              │
          [Clearance API Sync]           [PDF/A-3 Generation]
                  │                              │
        [Cleared by ZATCA API]           [Delivered to Client]
                  │                              │
          [Deliver to Buyer]            [Reporting API (24h)]

B2B Invoices (Standard Tax Invoices)​

  • Process: Clearance (real-time).
  • Execution: The invoice must be validated, signed, and submitted to the ZATCA Clearance API. The ZATCA API validates the XML in real-time, appends its cryptographic clearance signature, and returns it. The invoice can only be printed or emailed after receiving this clearance.

B2C Invoices (Simplified Tax Invoices)​

  • Process: Reporting (deferred).
  • Execution: The invoice is generated, stamped locally using the production CSID, and delivered to the customer immediately. The system is required to report the B2C XML payload to the ZATCA Reporting API within 24 hours of transaction generation.

3. Guardian Local Validation Engine​

To prevent API connection failures and rejections, BayanCore uses the Guardian Service to pre-validate fields:

  • Rule Enforcement: Evaluates invoices against 150+ ZATCA business rules (such as checking if postal codes are exactly 5 digits, verifying buyer VAT numbers contain 15 digits starting/ending with 3, and ensuring discount calculations balance).
  • Bilingual Error Handling: If validation fails, the Guardian Service translates cryptographic codes into plain language instruction cards:
    • System Error: Rule: BR-KSA-08, Category: Business, Text: [Buyer ID is missing]
    • BayanCore Translation: "Please add the customer's CR Number or National ID in the billing address tab before submitting."

4. Resiliency & Downtime Management​

If ZATCA servers become unreachable:

  • Idempotency & Queues: Invoices are queued in a local Redis database. The system automatically retries connection using exponential backoff with a randomized jitter, preventing duplication attempts.
  • Audit Trail Flagging: Invoices cleared during downtime are logged with an outage flag. Once connection is restored, the queue replays the backlog, updating transaction records with official clearance signatures.