Integration with ZATCA: How E-Invoicing Linkage Works

“Integration” is the technical step that turns your accounting system from a mere tool that issues invoices into a system connected directly to the Fatoora platform run bythe Zakat, Tax and Customs Authority (ZATCA). In Phase Two of e-invoicing it is no longer enough for your software to produce a formatted invoice. Your system must communicate with the Authority’s servers in real time, sign every invoice with a digital signature, and submit it for clearance or reporting before it reaches your customer.

This guide explains what integration means technically: how the integration works through the Application Programming Interface (API), what the registration process and the issuance of a CSID certificate involve, the practical step-by-step integration process, where the common challenges appear, and how a compliant accounting system such as Qoyod handles these details on your behalf.

What does “integration” mean in Phase Two of e-invoicing?

The Authority split the e-invoicing program into two phases. Phase One, which began on 4 December 2021, required businesses only to issue invoices electronically, without any direct connection to the Authority’s systems. The invoice was generated and stored inside the seller’s system.

Phase Two, which launched on 1 January 2023 in waves based on revenue size, added the “integration and linkage” requirement. Here your system becomes obligated to connect directly to the Fatoora platform. Every invoice passes through the Authority’s servers, either for prior clearance or for reporting within a set deadline.

The core difference is simple but profound. In Phase One the system worked in isolation from the Authority. In Phase Two the system became part of the Authority’s own network, exchanging data with it on every sale. This shift imposes precise technical requirements on the software you use.

The two invoice types in integration: cleared and reported

Before getting into the details of the integration, you need to understand that the Authority handles two types of invoices in two completely different ways. The type determines the invoice’s path within the integration process.

Standard tax invoice (B2B): Used in transactions between businesses. It is subject to the “Clearance” mechanism. Your system sends the invoice to the Fatoora platform, the Authority verifies it, stamps it, and returns it cleared, and only then can you deliver it to the buyer. This is a real-time process that happens before the invoice reaches the customer.

Simplified tax invoice (B2C): Used in sales to the end consumer. It is subject to the “Reporting” mechanism. Your system issues the invoice and delivers it to the customer immediately with the QR code, then reports it to the Authority within 24 hours. It does not wait for prior clearance.

The distinction matters in the integration design. B2B invoices require a synchronous connection and waiting for the Authority’s response before completing the sale, whereas B2C invoices allow the sale to be completed first and reported afterward. Learn the details in the guide to types of electronic invoices.

The technical components of an integrated invoice

When your system connects to the Authority, every invoice acquires new technical elements that did not exist in Phase One. These elements are what make the invoice “acceptable” to the Fatoora platform:

• Cryptographic Stamp: A digital signature created using a Public Key Infrastructure (PKI) certificate issued by the Authority. It proves the invoice was issued by an authorized system.
• Unique Identifier (UUID): A unique identification number for each invoice that prevents duplication and enables tracking.
• Previous Invoice Hash (Hash): A digital fingerprint of the invoice that preceded it, linking invoices into a connected chain that prevents deletion or tampering.
• QR Code: Contains the invoice data and the signature, and allows instant verification of its validity.
• Structured Format: The invoice is generated in XML format according to the UBL 2.1 standard adopted by the Authority, not as an ordinary PDF.

These elements are not written manually. The system generates them automatically in every invoice according to the Authority’s specifications. Any error in generating them means the invoice is rejected by the Fatoora platform.

How is the integration done technically through the Application Programming Interface (API)?

Integration is essentially an automated dialogue between your system and the Authority’s servers through the Application Programming Interface. The Authority provides a set of endpoints (API endpoints) that your system calls at different stages. Understanding these endpoints clarifies what happens behind the scenes in every sale.

1. Compliance endpoint

Before your system starts sending real invoices, it must pass the compliance tests. You send samples of standard and simplified invoices and credit and debit notes to a testing environment at the Authority. If the samples pass verification, your system is approved to move to production.

2. Onboarding endpoint (Onboarding and certificate issuance)

Here your system requests a CSID certificate from the Authority. It starts by creating a Certificate Signing Request (CSR) containing the business’s data, then sends it along with the activation code (OTP) obtained from the Fatoora portal. The Authority responds with the certificate, which the system uses to sign every subsequent invoice.

3. Clearance endpoint for standard invoices

When a B2B invoice is issued, the system sends it to the clearance endpoint. The Authority verifies the signature, the format, and the data, then returns the invoice stamped with its seal. The invoice may not be delivered to the buyer before this step.

4. Reporting endpoint for simplified invoices

When a B2C invoice is issued, the system delivers it to the customer immediately, then reports it to the Authority through the reporting endpoint within 24 hours. The Authority responds with an acknowledgment of receipt.

All these calls happen in the background within fractions of a second in a well-designed system. The cashier or accountant sees nothing of them except the appearance of the QR code and the stamp on the final invoice.

The CSID certificate: the cornerstone of integration

The CSID certificate is the identifier that proves your system is authorized to deal with the Fatoora platform. Without it, the system cannot sign any invoice with a signature the Authority accepts. That is why issuing and managing this certificate are the most important parts of the integration process.

The certificate goes through a clear life cycle:

• Creation: The system generates a private key and a Certificate Signing Request (CSR) containing the business name, its tax number, and the device or branch data.
• Activation: You log in to the Fatoora portal, register the issuing unit, and obtain an activation code (OTP) valid for a short period.
• Issuance: The system sends the signing request together with the activation code, and the Authority issues the CSID certificate.
• Usage: The system uses the certificate to sign every invoice with a cryptographic stamp.
• Renewal: The certificate has a validity period. The system must renew it before it expires so that issuance does not stop.

Note that each issuing unit (a point-of-sale device, a branch, or a system) has its own CSID certificate. A business with ten branches may need to manage ten certificates, each with an independent life cycle. This complexity is one of the main reasons for turning to an accounting system that handles the management automatically. To review the full requirements, see the e-invoicing readiness checklist.

The practical step-by-step integration process

If you wanted to describe the integration process to your IT manager, these are the steps in the order in which they actually happen:

Step 1: Confirm the system is ready

Verify that your accounting system genuinely supports Phase Two. It must generate XML according to UBL 2.1, support cryptographic signing, CSID certificate management, and connection to the API endpoints. A system that issues PDF invoices only is not qualified for integration.

Step 2: Log in to the Fatoora portal

Log in to the Fatoora portal through your business’s account with the Authority, and register the issuing units you want to integrate. Obtain the activation code for each unit.

Step 3: Create and issue the CSID certificate

From inside your accounting system, create the certificate signing request and enter the activation code. The system will handle connecting to the Authority, issuing the certificate, and storing it securely.

Step 4: Pass the compliance test

Send the required invoice samples to the testing environment. Make sure all invoice and note types pass verification without errors in format or signature.

Step 5: Move to production

After passing compliance, the system moves to the live environment. Real invoices begin passing through clearance or reporting according to their type.

Step 6: Continuous monitoring

Monitor the status of the invoices sent, deal with any rejected invoices, and track certificate validity. Integration is not a one-time event but an ongoing operational process.

Common challenges in the integration process

Many businesses stumble in integration for recurring technical reasons. Knowing them in advance saves you days of failed attempts:

• Errors in the XML format: The smallest error in the invoice structure under UBL 2.1 leads to its rejection. A missing field or wrong order is enough to fail verification.
• Problems in the cryptographic signature: If the cryptographic stamp is not applied correctly, the Authority rejects the invoice even if its data is sound.
• Certificate expiry: Forgetting to renew the CSID certificate stops issuance suddenly. A business may discover the problem only when the first invoice fails in the morning.
• Loss of connection to the Authority: B2B invoices need real-time clearance. Any network outage may disrupt sales if the system is not designed to handle such cases.
• Breaking the hash chain: The order of invoices and their linkage to one another must remain sound. Any flaw in the sequence raises questions with the Authority.
• Multiple issuing units: Managing separate certificates for each branch or device increases the chances of human error as the business grows.

These challenges are the real reason most businesses choose an integrated accounting system instead of building an in-house integration solution. Building a custom integration requires a team of developers, ongoing maintenance, and close tracking of every update the Authority releases. Compare the different paths in the guide to the phases of e-invoicing implementation.

How does Qoyod handle the integration process on your behalf?

The core idea of a compliant accounting system is that it hides the technical complexity behind a simple interface. You issue an invoice as usual, and the system handles everything related to the integration in the background. This is exactly what Qoyod does:

• Issuing the CSID certificate automatically: The system generates the signing request, connects to the Authority, issues the certificate, and stores it securely without any technical intervention from you.
• Cryptographic signing on every invoice: It applies the cryptographic stamp, the unique identifier, the previous invoice hash, and the QR code to every invoice according to the Authority’s specifications.
• Real-time clearance for standard invoices: It sends B2B invoices to the Fatoora platform, waits for clearance, and returns them stamped and ready for delivery.
• Reporting within 24 hours for simplified invoices: It reports B2C invoices to the Authority automatically within the set deadline.
• Generating XML according to UBL 2.1: It produces every invoice in the correct structured format without you writing a single line.
• Preserving the hash chain: It links invoices into a sound chain that ensures data integrity for future verification.

What Qoyod does not do also matters, so that your expectations are accurate. The system does not register you with the Authority on your behalf, since registering on the Fatoora portal and linking issuing units is a step the business performs itself, but Qoyod guides you step by step. Likewise, the system does not file the tax return for you, but rather prepares the return summary for you to submit through the Authority’s portal.

To review the technical details of the integration in Qoyod, see the page Integration with the Zakat, Tax and Customs Authority, and the page Phase Two readiness. And if you have your own system you want to integrate, then Qoyod’s integration APIs let you integrate directly.

In-house integration versus a compliant system: which path do you choose?

A business has two paths for integrating with the Fatoora platform. The first path is to build a custom in-house integration that connects to the API endpoints directly. The second path is to use a compliant accounting system that handles the integration ready-made. Each path has its own cost and requirements.

Building an in-house integration gives you full control, but it imposes heavy burdens. You need a team of developers who understand the UBL 2.1 standard, cryptographic signing, and Public Key Infrastructure. You need a testing environment, constant tracking of every update the Authority releases, and a support team to handle rejected invoices. Any gap in the code may disrupt invoicing and expose you to violations.

The compliant system transfers these burdens to the service provider. It generates the certificates, signs the invoices, tracks the Authority’s updates, and fixes errors before they reach you. You focus on your business, and the system stays compliant automatically. This is why most owners of small and medium-sized businesses choose this path.

The practical rule is clear. If you have complex existing systems and a large technical team, direct integration through the integration APIsmay suit you. But if you want a fast and reliable integration without a technical burden, the compliant system is the smarter choice.

What happens when an invoice is rejected?

Not every invoice is accepted on the first attempt. The Fatoora platform may reject an invoice for several reasons, and understanding how to handle rejection is an essential part of successful integration.

When a standard invoice is sent for clearance, the Authority verifies the signature, the format, and the data. If it finds an error, it responds with a rejection message containing the error code and its description. The rejected invoice is not delivered to the buyer, and the error must be corrected and the invoice resent.

The most common reasons for rejection: an incorrect tax number, a missing mandatory field, an error in calculating the tax, an invalid cryptographic signature, or a flaw in the hash chain sequence. Each reason has a specific error code that helps diagnose the problem.

Here the value of the compliant system appears again. A good system catches most errors before sending through prior verification, reducing rejections to a minimum. And when a rejection occurs, it displays a clear message instead of an obscure technical error code. This saves the accountant significant time and effort.

Neglecting rejected invoices is not an option. Every sales invoice must be cleared or reported. Accumulating rejected invoices without correction means an incomplete tax record that may expose you to accountability from the Authority.

Data security in the integration process

Integration means exchanging sensitive data between your system and the Authority’s servers on every sale. This imposes precise security requirements on the system you use.

The private key associated with the CSID certificate must be stored with complete security. If this key were to leak, another party could sign invoices in your business’s name. That is why the compliant system stores it in an isolated encrypted environment, and does not expose it even to the system’s own users.

Likewise, invoices are transmitted to the Fatoora platform over encrypted communication channels, and the hash chain is preserved to ensure no invoice is tampered with after issuance. These security layers protect your business and ensure your tax record is sound and auditable at any time.

When do you need a compliant system immediately?

If your business is registered for value-added tax and falls within one of the Phase Two waves, integration is not an option but an obligation. The Authority announces each wave about six months before its date, based on annual revenue size. Always confirm your wave date through the official notice from the Authority, not by assumption.

Businesses that wait until the last moment face double pressure: learning the new system, issuing the certificates, and passing compliance, all under the pressure of the deadline. It is better to integrate your system early, test the process calmly, and enter your wave date ready.

For small and medium-sized businesses specifically, the compliant system offers a shortcut. Instead of hiring developers to build a custom integration, you get a ready-made, tested integration that is continuously updated with every change the Authority releases. This ensures continuous compliance for you without an internal technical burden.

The cost of delaying integration is not only technical. A business that passes its wave date without an actual integration exposes itself to violations and fines the Authority may impose. Continuing to issue non-compliant invoices also disrupts your relationship with your business customers, who are in turn obligated to receive cleared invoices to record their input tax. Timely integration is not merely a regulatory obligation, but a condition for the continued smooth commercial dealings with your partners in the Saudi market.

Many businesses discover too late that the old system they use does not support Phase Two at all, so they are forced into a rushed transition under pressure. Migrating early to a compliant system gives you room to move your data, train your team, and test the process calmly before integration becomes mandatory in your wave.

How Qoyod helps you

Qoyod is a Saudi accounting system compliant with Phase Two of e-invoicing. It handles integration with the Fatoora platform completely: CSID certificate issuance, cryptographic signing, real-time clearance for standard invoices, and reporting within 24 hours for simplified invoices. You issue an invoice with a click, and the system handles the technical details in the background.

Instead of managing separate certificates for each branch, tracking the Authority’s updates, or worrying about rejected invoices, you get a system that continuously updates itself to stay compliant. And Qoyod support is available 24 hours, seven days a week to help you with any question about integration or compliance.

Frequently asked questions about integration with the Authority

What is the difference between integration and electronic issuance?
Electronic issuance (Phase One) means generating the invoice digitally inside your system without a connection to the Authority. Integration (Phase Two) means your system connecting directly to the Fatoora platform to clear every invoice or report it in real time.

What is a CSID certificate?
It is a digital certificate the Authority issues for each issuing unit, which your system uses to sign invoices with a cryptographic signature that the Fatoora platform accepts. Without it, cleared invoices cannot be issued.

Do I need a developer to complete the integration?
If you use a compliant accounting system such as Qoyod, no. The system handles the technical side completely. You need a developer only if you choose to build a custom integration for your in-house system.

How long does the integration process take?
With a ready system, registration, certificate issuance, and passing compliance can be completed in a short time. Building a custom integration from scratch may take weeks or months depending on your technical team’s readiness.

What happens if the CSID certificate expires?
Your system stops issuing cleared invoices until you renew the certificate. The compliant system tracks validity and renews the certificate before it expires to avoid a halt in sales.

Does Qoyod file the tax return for me?
No. Qoyod prepares a summary of your tax return (output tax, input tax, net amount due) for you, but filing the return and paying the tax are done through the Authority’s portal by yourself.

For a deeper understanding of the related concepts, see the definition of e-invoicing and the definition of value-added tax in the accounting terms glossary. And if you are at the start of your journey, the guide to Phase One of e-invoicing explains the foundation on which integration is built.