Zatca Technical workflow

Onboarding is mandatory for all taxpayers who are subject to electronic invoicing in Saudi Arabia. As a result of the onboarding process, taxpayers obtain Cryptographic Stamp Identifiers (CSIDs). CSIDs are required for integration with the electronic invoicing portal that is managed by the Saudi Arabian tax authority (ZATCA) and for further submission of electronic invoices.

This article explains how to onboard taxpayers and their electronic invoicing software with Saudi Arabian tax authorities.


Onboarding process

The onboarding process consists of two steps:

  1. Obtain a Compliance CSID (CCSID), which ZATCA assigns to perform compliance checks of Electronic invoice generation solutions (EGSs).
  2. Obtain a Production CSID (PCSID), which ZATCA assigns to compliant EGSs.

Obtain a CCSID

  1. In the Saudi Arabian Taxation Portal (Fatoora), go to the Onboarding and Management Portal by selecting the relevant tile.

  2. On the main landing page of the Onboarding and Management Portal, select the Onboard new solution unit/device tile, and then select Generate OTP code. The OTP code is only valid for one hour after it's generated. Make sure that it's used within that time frame.

  3. Select the number of one-time password (OTP) codes to generate. The number depends on the number of e-invoicing generation units (devices) that will be used.

  4. Save the generated OTP codes so that you can use them in later steps.

  5. Prepare a configuration file for the certificate signing request. This configuration file should be in the form of a plain text file that contains the following data.

  6. Save the file to the same location as the on boarding script with the name, csr_config.txt.

  7. Run the onboarding script . Specify the OTP and configuration file as input parameters. Here is an example

Compliance check

After you obtain Compliance CSID using the PowerShell script, ZATCA requires you to complete certain compliance checks by submitting sample invoices. This step is a prerequisite to request a Production CSID.

Ensure that all types of sample invoices that were configured in the Certificate Signing Request (CSR) configuration file are successfully submitted to ZATCA. Use the standard process for issuing electronic invoices. For more details, see Issue electronic invoices in Finance and Supply Chain Management.

Use the feature, "Saudi Arabian ZATCA compliance check (SA)" in RCS and follow the Country/region-specific Configuration section steps using the Compliance CSID you obtained.

After the compliance checks are successfully complete, use the PowerShell script to obtain Production CSID (refer on-boarding script).

Obtain a PCSID

To obtain a PCSID, you must correctly configure the solution for electronic invoice generation and submission, and the solution must be fully functioning. To achieve this result, you must complete all the required preliminary configuration steps. 

  1. Make sure that all electronic invoices are successfully submitted to ZATCA.

  2. Run the onboarding script that is provided later in this article. Specify the CCSID as an input parameter. Here is an example

  3. The PCSID is received as a certificate file in PFX format
  4. After you complete all the configurations steps, the system is ready to be used in production mode.To review obtained CSIDs on the ZATCA side, use the Review Existing Cryptographic Stamp Identifier (CSID) tile on the landing page of the Onboarding and Management Portal.
Developer portal/sandbox api link
simulation portal api link
https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation Live Production api link

Above api link used for compliance check sending xml, CSID, PCSID all are as per above api selection mode.

References :
Fatoora Technical Details Document link
https://zatca.gov.sa/ar/E-Invoicing/Introduction/Guidelines/Documents/E-invoicing Detailed Technical Guidelines.pdf
Security Feature Document link


Data Dictionary Document link

https://zatca.gov.sa/ar/E-Invoicing/SystemsDevelopers/Documents/20230519_EInvoice_Data_Dictionary vF.xlsx
Fatoora Portal Document link 
Xml standard document 
Faqs : invoice indicators on invoice form


Q1:  When making the invoice, what is the evidence that it has reached the site of Zakat?

Answer : it will say REPORTED or CLEARED, in the api status

Q2:  How get live credentials 

Ans:  read from page 19 onward https://zatca.gov.sa/ar/E-Invoicing/Introduction/Guidelines/Documents/E-invoicing%20Detailed%20Technical%20Guidelines.pdf

Q3: How can I know if this is a credit note from XML,Both its show invoice. Are you mapping an invoice with a credit note in xml?

Ans:yes,InvoiceDocumentReference in this field

InvoiceTypeCode field is use for invoice,credit,debit note as per code 388,,381,383

Q4. how get simulation portal OTP and check device listing on portal?

Ans: use following link and open portal, then go through page 17 and onward you will get to know how to do it.


Learning JavaScript beginner to advance guide
--> AlhadiTech