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:

1. Adding the Tax Identification Number Correctly
   From:
   Settings → General Settings

2. 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

3. Invoice Designer is Complete

   • It must contain all required fields

   • You can verify this using the guidance menu located next to the invoice designer

4. 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

1. Go to Settings

2. Select Electronic Integration

3. Select Fatoora Portal

4. Click Start Integration

5. 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:
  ZATCA’s Fatoora Portal

Steps to Extract the Code:

1. Log in to the business account on the authority’s website

2. Access Fatoora Portal

3. Click Initialize New Device/Unit

4. Select the number of verification codes:

   • From 1 to 100 codes per hour

5. Click Create Activation Code

6. A list of codes will appear

7. Select only one code

Third: Enter the Verification Code in Qoyod

1. Return to the integration page in Qoyod

2. Enter the verification code manually

   • It cannot be copied or pasted

   • It must be typed digit by digit

3. 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