The complete steps for connecting Qoyod with the Zakat, Tax and Customs Authority (ZATCA) in Phase 2 of e-invoicing, from preparation, through obtaining the verification code from the Fatoora Portal, to confirming the connection succeeded and resolving the common errors.
Path in Qoyod
Settings › Electronic Connection › Fatoora Portal › Start Connection
Before you start
Before attempting the connection, make sure of the following points:
- The tax identification number is added correctly, from: Settings, then General Settings.
- The business name is in English, written in the business name field, in English, one word, and short. The name can be edited later, after the connection succeeds.
- The invoice designer is complete: it must contain all the required fields. You can verify this through the guidance menu next to the invoice designer.
- Phase 1 is activated: Phase 2 cannot be connected while Phase 1 is not activated. See How to Enable E-Invoicing (Phase One) and Display QR Codes on Invoices.
Step 1: open the connection page in Qoyod
- Go to Settings.
- Select Electronic Connection.
- Select Fatoora Portal.
- Click Start Connection.
- You will be asked for a verification code.
The verification code does not arrive by SMS or email. You have to obtain it manually from the Fatoora Portal.
Step 2: get the verification code from the Fatoora Portal
The portal is at ZATCA’s Fatoora Portal.
- Sign in to your business account on the authority’s website.
- Go to Fatoora Portal.
- Click Initialize a New Unit/Device.
- Select the number of verification codes, from 1 to 100 codes per hour.
- Click Create Activation Code.
- A list of codes appears.
- Select one code only.
Step 3: enter the verification code in Qoyod
- Return to the connection page in Qoyod.
- Enter the verification code manually. It cannot be copied or pasted, so type it digit by digit.
- Click Save.
The code is valid for one hour only. If it expires, generate a new code and use it immediately. Entering an expired code may display the error Exceed Character Limit.
How to confirm the connection succeeded
An activated icon appears next to the authority connection, which means the connection succeeded.
- The connection is made only once for the business.
- It is activated automatically for all users.
- Any new invoice issued after the connection is sent to the authority automatically. For what the statuses and alerts on those invoices mean, see Guide to E-Invoice Statuses After ZATCA Submission.
- Old invoices show the status not applicable.
Notes
- There is no separate field for the business name in English. It is entered in the business name field.
- The address must be in Arabic, with Saudi Arabia as the country. Otherwise the error “You do not have permission to access” may appear.
- You can choose an official connection or a simulation (testing) connection, depending on the environment type selected.
- If the business tax identification number is changed after the connection is completed, contact the Zakat, Tax and Customs Authority to be informed of the procedures you must follow.
Solving common connection errors
Message: “Something went wrong, please try again”
Make sure the business name is in English and one word, and that the tax identification number is correct, then retry after editing the name.
Message: Exceed Character Limit
The cause is an expired code, more than one hour old. Generate a new code and enter it manually straight away.
Connection status: “Processing”
Check the business name (English, one word), the tax identification number, the address in Arabic with Saudi Arabia as the country, the correct connection type (official or testing), and that Phase 1 is activated.
If everything is correct, sign out of the authority’s website, sign back in, create new codes, and try again. For the full checklist, see Resolving ZATCA Integration Issues (Phase Two).
Supporting material
A short training course explaining the connection steps in a simplified way: watch the video walkthrough. It helps reduce errors during implementation.
