How to Connect Qoyod with ZATCA via Fatoora Portal: Phase 2 E-Invoicing, Verification Codes, and Troubleshooting

Phase Two of E-Invoicing (Fatoora Portal)

This guide explains the complete steps to integrate Qoyod software with the General Authority of Zakat and Tax (ZATCA) in Phase Two of E-Invoicing, starting from setup, through obtaining a verification code from the Fatoora Portal, and ending with confirming successful integration and resolving common errors.

Before You Start (Very Important)

Before attempting to integrate, make sure the following points are confirmed:

Adding the Tax Identification Number Correctly
From:
Settings → General Settings
Business Name in English
- Enter it in the Business Name field
- It should be:
  - In English
  - A single word
  - Short
The name can be changed later after successful integration
Invoice Designer is Complete
- It must contain all required fields
- You can verify this using the guidance menu located next to the invoice designer
Phase One Activation
- Phase Two cannot be integrated if Phase One is not activated

Video and Supporting Files (Sent to Customer)

It is recommended to send the following materials to the customer before or during the explanation:

A short training course that explains the integration steps in a simplified manner
File: Method for Integrating Phase Two of Electronic Invoicing
File: Comprehensive E-Invoicing Content

(These materials help reduce errors during implementation)

Steps to Integrate Qoyod with the General Authority of Zakat and Tax (Phase Two)

First: Access the Integration Page in Qoyod

Go to Settings
Select Electronic Integration
Select Fatoora Portal
Click Start Integration
You will be asked for a verification code

Note:
The verification code will not arrive via SMS or email
You must obtain it manually from the Fatoora Portal

Second: How to Obtain the Verification Code from Fatoora Portal

Accessing the Fatoora Portal

Fatoora Portal Link:
https://fatoora.zatca.gov.sa/

Steps to Extract the Code:

Log in to the business account on the authority’s website
Access Fatoora Portal
Click Initialize New Device/Unit
Select the number of verification codes:
- From 1 to 100 codes per hour
Click Create Activation Code
A list of codes will appear
Select only one code

Third: Enter the Verification Code in Qoyod

Return to the integration page in Qoyod
Enter the verification code manually
- It cannot be copied or pasted
- It must be typed digit by digit
Click Save

Very Important Note

Code validity: One hour only
If the validity expires:
- A new code must be generated
- And used immediately
Entering an expired code may result in an error:
Exceed Character Limit

How to Verify That Integration Was Successful?

An enabled icon will appear next to the authority integration
This means the integration was successful

After Successful Integration:

Integration is done only once per business
It is automatically activated for all users
Any new invoice after integration:
- Is automatically sent to the authority
Old invoices:
- Appear with status “Not Applicable”

Very Important Notes

There is no separate field for the business name in English
It should be entered in the Business Name field
The address must be:
- In Arabic
- Country: Saudi Arabia
- Otherwise, an error may appear:
  “You do not have permission to access”
You can choose:
- Official Integration
- Or Simulation (Test)
  Depending on the environment type selected
If the business’s tax identification number is changed after completing the integration, please contact the General Authority of Zakat, Tax and Income to be informed of the procedures you should follow.

Resolving Common Errors During Integration

Message: “An error occurred, please try again”

Make sure:

Business name is in English + single word
Tax identification number is correct
Try again after modifying the name

Message: Exceed Character Limit

Reason:

Code has expired (more than one hour)

Solution:

Generate a new code
Enter it immediately manually

Integration Status: “Processing”

Check:

Business name (English, single word)
Tax identification number
Address in Arabic and country Saudi Arabia
Select the correct integration type (Official / Test)
Activate Phase One

If everything is correct:

Log out from the authority website
Log in again
Create new codes
Try again

Keywords for Inquiry
- How do I integrate with the Zakat Authority?
- How do I integrate with the authority?
- I want to do Phase Two of E-Invoicing, what do I do?
- What is the method for integrating with Fatoora Portal?
- Why is the verification code not arriving from the General Authority of Zakat and Tax?
- I need to integrate with the authority
- I was trying to integrate with the authority
- I don’t know where to get the verification code from the authority
- How do I enter the integration code in Qoyod?
- I need to integrate with Zakat
- Integration with the General Authority of Zakat and Tax
- We want to integrate with tax
- I see an option to integrate with Fatoora Portal, what are the steps?
- Why is the integration with the authority not working for me?
- How to integrate Qoyod software with the tax and zakat system?
- Integration with the General Authority of Zakat
- How do I know if integration was successful?
- I need to integrate with the General Authority of Zakat and Income
- I want to integrate with Zakat and Income Phase Two
- Do I have to change the business name for integration to work?
- Activating Fatoora Portal.
- I received activation of Fatoora Portal.
- Electronic integration was rejected “An error occurred, please try again”.
- How do I get the verification code that I obtained from the General Authority of Zakat and Tax?
- When integrating with Zakat, where do I get the integration number?
- We need to integrate with Zakat.
- Enter the verification code you obtained from the General Authority of Zakat and Tax. How do I get it?
- I want to integrate with the authority.
- I need a way to integrate sales invoices with the authority.
- Integration with the General Authority of Zakat and Tax.