Comment on page
Learn E-Invoicing KSA API Basics
E-invoicing will be implemented in two phases:
- Phase One, known as the Generation phase, is enforceable as of December 4, 2021.
- Phase Two, known as the Integration phase, is enforceable starting from January 1, 2023 and implemented in waves by targeted taxpayer groups. Taxpayers will be notified by ZATCA on the date of their integration at least 6 months in advance.
The requirement phasing is summarized in the “How to get ready” section below.
For additional details, please check the simplified guideline https://zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/E-Invoicing_Detailed__Guideline.pdf
The technical requirements are typically implemented by solution providers (e.g. cash register vendors, software vendors) or the internal technical teams for in-house built solutions. Taxpayers may approach a solution provider or their internal technical teams to acquire or upgrade to a compliant electronic system; and ensure they are generating compliant invoices starting from December 4th, 2021.
E-invoicing applies to all persons subject to VAT and any other parties issuing tax invoices on behalf of suppliers subject to VAT.
Non-resident taxable persons for VAT purposes are excluded.
- All persons subject to the E-Invoicing Regulation must use compliant electronic systems to generate invoices starting from December 4th, 2021. Manual invoices will no longer be considered compliant invoices.
- E-invoices must include the minimum additional fields (see next question).
- E-invoicing compliant electronic systems should be able to generate QR codes.
- E-invoicing compliant electronic systems must not allow for the prohibited functions specified by ZATCA.
- Please approach your solution provider or your internal technical teams to ensure your electronic systems are compliant with ZATCA requirements. In addition, developers and subject matter experts may visit ZATCA’s website for viewing all requirements (business, technical, security, etc.).
- E-invoices for Phase 1 (4 December 2021) are similar to current invoices, with minimum additional fields:
- For simplified tax invoices and their associated notes (usually issued for B2C transactions) a mandatory QR code.
- For tax invoices and their associated notes (usually issued for B2B transactions), an optional QR code and mandatory VAT number of the buyer if the buyer is a registered VAT taxpayer.
- There is no specific file format mandated for Phase 1, however, invoices must include the mandatory fields and be issued from an electronic system meeting ZATCA’s requirements. In addition, electronic copies of all issued invoices must be stored by the taxpayer.
Yes, the system or solution used for generating and storing the invoices must be able to have internet connectivity for both phases.
No, integration with ZATCA is not required for Phase One starting December 4, 2021.
Yes, QR codes are mandatory for simplified tax invoices (usually issued for B2C transactions) and optionally for tax invoices (usually issued for B2B transactions). QR code is not provided by ZATCA and shall be generated by the electronic system. Please approach your solution provider or technical teams to acquire or upgrade to a compliant electronic system.
As part of Phase 1 (Generation Phase), the below fields are the minimum required fields that must be shown after scanning a QR code in a simplified tax invoice:
- 1.Seller’s name
- 2.VAT registration number of the seller
- 3.Timestamp of the Electronic Invoice or Credit/Debit Note (date and time)
- 4.Electronic Invoice or Credit/Debit Note total (with VAT)
- 5.VAT total
No, for Phase 1 (December 4, 2021), taxpayers are not required to approve, clear, or report invoices to ZATCA.
- Lack of user management capabilities (uncontrolled access) for example:
- Anonymous Access
- Absence of user session management
- Tampering with e-invoices or their associated notes or logs
- Multiple Electronic Invoice sequences
- For additional details on the prohibited functionalities, please refer to Annex (1) “Technical Requirements of E-invoice Generation Solutions” in the resolution.
- Taxpayers should take steps to ensure their E-Invoicing solutions are properly functioning at all times (e.g. battery back-up).
- However, if despite taking necessary steps the taxpayer faces incidents, technical errors, or emergency matters which hinder the generation of electronic invoices or electronic notes, the taxpayer must:
- Communicate immediately with their solution provider and technical teams to resolve the issue, and keep evidence of their communication (e.g. e-mail).
- Notify ZATCA immediately of the failure through this link. https://zatca.gov.sa/en/E-Invoicing/FailureNotifications/Pages/VerifyTaxpayer.aspx
Upon resolution of the issue, the taxpayer shall notify ZATCA via the above link and resume the generation of e-invoices for all transactions conducted during the interruption period.
Taxpayers should notify ZATCA only of incidents in which they are no longer able to generate e-invoices. A taxpayer with multiple E-Invoicing solutions is not required to notify ZATCA of the failure of a single solution in case they are still able to generate e-invoices using another e-invoicing solution.
After notifying ZATCA, taxpayers may continue to conduct business during solution failure to their customers. Any invoices or notes related to transactions conducted during the solution failure must be generated electronically promptly as soon as the failure incident is resolved.
- Phase 1 known as the Generation phase will require taxpayers to generate and store compliant tax invoices and notes using compliant electronic systems.
- Phase 1 is enforceable as of December 4th, 2021 for all Persons subject to the E-Invoicing Regulation.
The enforcement date for the first target group will not be earlier than January 1, 2023. And ZATCA will notify taxpayers of their Phase 2 wave at least six months in advance.
- Phase 2, which will be implemented in waves by target taxpayer groups starting from Jan 1st, 2023, entails additional technical requirements that e-invoicing electronic systems must comply with, the integration of taxpayer electronic systems with ZATCA, and the issuance of electronic invoices in a specific format.
- Due to the technical nature of the published requirements, it is recommended for taxpayers to approach a solution provider or your internal technical teams to ensure your electronic systems are compliant with ZATCA requirements. In addition, developers and subject matter experts may visit ZATCA's website for viewing all requirements (business, technical, security, etc.).Further details on the integration mechanisms and specifications will be published by ZATCA on the developer page on ZATCA's website.
- All prohibited functionalities that are part of Phase 1
- Export of stamping key
- Time change
- For additional details on the prohibited functionalities, please refer to Annex (1) “Technical Requirements of E-invoice Generation Solutions” in the resolution.
Please refer to the e-invoicing simplified guideline for information about the integration wave. https://zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/E-invoicing_Simplified%20GL.pdf
A taxpayer can use the same e-invoicing solution that was used for Phase 1, by updating the e-invoicing solution to comply with the Phase 2 requirements.
Yes, a taxpayer should continue following Phase 1 requirements until the integration enforcement date of the taxpayer’s wave, in which the taxpayer is required to start following Phase 2 requirements.
The taxpayer is not required to implement Phase 2 requirements until notified by ZATCA about the integration enforcement date of the taxpayer’s wave, in which the taxpayer is required to start following Phase 2 requirements.
Taxpayer accesses FATOORA portal (https://fatoora.zatca.gov.sa/) using Taxpayer Portal credentials (ERAD), Then follow the EGS onboarding process and for more details please refer to the Fatoora portal user manual. https://zatca.gov.sa/ar/E-Invoicing/Introduction/Guidelines/Documents/Fatoora_Portal_User_Manual.pdf
After successful onboarding of each EGS, the taxpayer will be notified indicating whether the e-invoicing solution has been successfully integrated. Also, taxpayers can use the FATOORA Portal in order to view a summary list of all their integrated e-invoicing solutions.
- Phase 2, known as the Integration phase, where subjective taxpayers must comply with Phase 2 business and technical requirements for the electronic invoices and electronic solutions, and the integration with ZATCA's system.
- Phase 2 is enforceable starting from January 1, 2023, and implemented in waves by targeted taxpayer groups. Taxpayers will be notified by ZATCA on the date of their integration at least 6 months in advance.
No, ZATCA may enforce such requirements in the future.
- Please refer to the “Invoicing and records guideline” section 4.1.2 here https://zatca.gov.sa/en/HelpCenter/guidelines/Documents/Invoicing%20and%20Records.pdf
- Please also note that e-invoices are not required for the following transactions:
- Exempt supplies
- Import of goods
- Supplies subject to reverse charge mechanism
Yes, however, Non-resident taxable persons for VAT purposes are excluded.
No, Persons subject to the E-Invoicing Regulation may use any invoicing system, provided that it complies with the requirements of the Authority.
Is there a specific period? The period for storing/keeping invoices does not differ from the period specified according to the statutory requirements in the Implementing Regulations of the Value-Added Tax Law.
Yes, in accordance with article 66 in the Implementing Regulations of the Value-Added Tax Law. In case a cloud e-invoicing solution or a cloud data center located outside the kingdom is used, an extension or access to data must be available in the branch that is located in the kingdom, and it should allow access to all related records. Additionally, non-tax-related regulations may apply to the taxpayer entity, such as National Cybersecurity Authority and/or National Data Management Office published laws and any other applicable regulations or controls.
Receiving an advance payment should result in the issuance of an electronic invoice and not only a receipt voucher, as per Para (1) of Article 53 of VAT Implementing Regulations.
Persons subject to the E-Invoicing Regulation must provide a copy of the tax invoice or its related credit/debit note that is electronically generated with the clients.
A printed copy of the simplified tax invoice or its related credit/debit note must be provided to the clients/buyers, however, and based on mutual agreement between the seller and client/buyer, the invoice can be shared electronically or through any other way where the client/buyer can read it.
No, based on the VAT regulation, after issuing an invoice, it is prohibited to modify or cancel the invoice. and according to the regulation, debit/credit notes must be generated to modify or cancel the generated invoice. Therefore the supplier should issue an electron credit/debit note linked to the original modified invoice.
The generated tax invoice type depends on the transaction type. For transactions between a company and an individual, a simplified tax invoice must be generated. On the other hand, if the transaction is between two companies, a tax invoice usually will be generated based on the value of the supply. And the same invoicing system can be used to issue both types of tax invoices provided that it covered the requirements for each tax invoice.
- For exports, an electronic invoice must be generated in accordance with the E-invoicing Regulation.
- For imports, it is not subject to the E-invoicing Regulation.
No, there is no impact or change on the declaration process.
Yes, according to Paragraph (5/b) of Article 53 of the VAT implementing regulation, an invoice reference number must be visible on the invoice to identify the tax invoice. The regulation does not specify the format of this number. Taxpayers can use different formats for the invoice reference number so long as it uniquely identifies the tax invoice.
The invoice sequence mentioned within the prohibited functions under Paragraph (2/E) of Article 3 in the Controls, Requirements, Technical Specifications, and Procedural Rules for Implementing the Provisions of the E-Invoicing Regulation does not refer to the invoice reference number that identifies the tax invoice.
The invoice sequence mentioned under the prohibited functions refers to the technical ability of the e-invoicing solution to issue invoices using multiple sequence counters.
To get ZATCA’s approval on Special billing arrangements please follow the link and complete the application. https://s2c.gazt.gov.sa/A/705d6b48
ZATCA will review and notify the Taxpayer of the results.
- Online cash registers, virtual cash registers on tablets, e-invoicing software installed on a computer, e-invoicing software installed on a phone or tablet and cloud-based solutions are examples of e-invoicing solutions.
- Such electronic systems must comply with the specifications published by ZATCA.
- Please approach your solution provider or your internal technical teams to ensure your electronic systems are compliant with ZATCA requirements. In addition, developers and subject matter experts may visit ZATCA’s website for viewing all requirements (business, technical, security, etc.).
A QR code is a coded representation of readable text. In the context of e-invoicing, the QR code should contain specific information in a specific format.
- 1.Seller's Name
- 2.VAT registration number of the seller
- 3.Timestamp of the electronic invoice or credit/debit note (date and time)
- 4.Electronic invoice or credit/debit note total (with VAT)
- 5.VAT amount
- 6.Hash of XML electronic invoice or credit/debit note
- 7.Elliptic Curve Digital Signature Algorithm (ECDSA) signature
- 8.ECDSA public key. The public key BLOB format contains only the public portion of an ECDSA key used to generate the Cryptographic Stamp. The length of the public key BLOB for a 256-bit key is 64 bytes (72 bytes including magic number and field length information on some systems).
- 9.For Simplified Tax Invoices and their associated notes, the ECDSA signature of the cryptographic stamp’s public key by ZATCA’s technical CA is required.
An ECDSA signature is encoded according to IEEE P1363. This signature format encodes the (r, s) tuple as the concatenation of the big-endian representation of r and the big-endian representation of s. Each of these values is encoded using the number of bytes required to encode the maximum integer value in the key's mathematical field. For example, an ECDSA signature from 256-bit elliptic curves (like secp256k1) encodes each of r and s as 32 bytes, and produces a signature output of 64 bytes. Please find below an example.
public static byte[] extractR(String digitalSignature) throws Exception {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hash = digest.digest(Base64.getDecoder().decode(digitalSignature.getBytes(StandardCharsets.UTF_8)));
return Arrays.copyOfRange(hash, 0, 32);
}
/**
* Extract S Component
*
* @return
* @throws Exception
*/
public static byte[] extractS(String digitalSignature) throws Exception {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hash = digest.digest(Base64.getDecoder().decode(digitalSignature.getBytes(StandardCharsets.UTF_8)));
return Arrays.copyOfRange(hash, 32, 64);
}
In the context of e-invoicing, users should scan the QR code on e-invoices, debit notes, and credit notes by using the ZATCA VAT app. This app is available on the Google Playstore and iOS App Store free of charge.
If an XML has error(s), specific error message(s) will be displayed. Error(s) are likely to occur in cases such as when a mandatory field is missing or a value is in an incorrect format. The user may require the assistance of a technical expert to solve the error(s).
The CSID is technically a cryptographic certificate, which is a credential that allows for authenticated signing and encryption of communication. The certificate is also known as a public key certificate or an identity certificate. It is an electronic document used as proof of ownership of a public key.
The CSID is used to uniquely identify an Invoice Generation Solution Unit in possession of a taxpayer for the purpose of stamping (technically cryptographically signing) Simplified Invoices and for accessing the Reporting and Clearance APIs using TLS authentication.
Yes. As long as the VAT Registration number on the CSID matches the VAT Registration Number on the documents. In other words, for every VAT Registration Number being tested across any API call, a CSID with the same VAT Registration Number is required. Note that the VAT Registration number can be any dummy number that meets the syntax specifications (15 digits, starting with 3 and ending with 3).