Common Issues When Integrating with ZATCA

Common Issues When Integrating with ZATCA

When clients attempt to integrate with ZATCA, they may encounter the following error message on the cashier screen:

Here’s a step-by-step checklist to troubleshoot the issue:

1. Cashier App Version

1. Ensure the cashier app is version 5.0.81 or later
   
   

2. To check the version:
   
   

   • Navigate to: Console > Manage > Devices > Device Page

3. Locate the App Version field.

1. Branch Settings Validation 

Required Fields to Validate:

• Business/Branch Commercial Registration Number

• Business/Branch Tax Registration Name

• Business/Branch Tax Number

• Branch Street Name

• Branch Building Number

• Branch Additional Number

• Branch City

• Branch District

• Branch Postal Code

How to validate:

• Go to Business Details and copy the TRN and CRN.

• Visit the official ZATCA validation tool:
  
  

Search by using the CR
https://zatca.gov.sa/ar/eServices/Pages/TaxpayerLookup.aspx 

Match the Business Name and TRN  exactly with what's listed in the Branch Details.

Also, validate the Commercial Registration Number at the bottom of the page:

1.  TAX Group Assignment:

• Ensure the client has assigned a TAX group to all entities that a tax group can be assigned to: products, modifier options, branches, and charges. 

• Even if the price of the products or modifiers is 0 tax group must be assigned
  
  

2. OTP Activation: 

• The OTP must be obtained from the Fatoora Portal, not the test environment.

• Important OTP Rules:

• Must be used only once

• Valid for one device and 1 hour

• Sync cashier data before entering the OTP-

• If activation fails, generate a new OTP and try again

1. Invoice Sync Status

• Once activation succeeds, advise the client to enable the Invoice Sync Status field on the Orders Page. This helps them track the sync status of each order.

• It will apply only to incoming invoices and will not affect any previous invoices.