ZATCA Phase 2

Phase 2 connects your store to ZATCA. Each new invoice is turned into signed XML and sent to ZATCA. Simplified (B2C) invoices are reported. Standard (B2B) invoices are cleared first and held back from the buyer until then.

Warning: Phase 2 sends real tax data in the Simulation and Production environments. Rehearse the whole flow in Sandbox and Simulation first, ideally on a copy of your store, and check ZATCA's current requirements before you go live.

#Before you start

• Phase 1 is on, with your seller legal name and VAT number.
• The seller name is at most 120 bytes (about 60 Arabic letters).
• You have access to the ZATCA Fatoora portal to get a one-time code (OTP). For the sandbox, use the ZATCA developer portal.
• WooCommerce's background scheduler runs on your site. Reporting and clearance run in the background.
• You can add a line to your site's wp-config.php file, or your host can do it for you.

#Step 1: Choose the environment

ZATCA has three environments. Each one onboards by itself; credentials are never copied between them.

1. In the ZATCA e-invoice (Phase 2) card, under Environment, choose the ZATCA environment.
2. The page shows the line to add to wp-config.php, above "That's all, stop editing!". Add it exactly as shown.
   • For the sandbox, the line is define( 'VITE_INVOICE_ZATCA_P2_SANDBOX', true );
   • For Simulation and Production, it is VITE_INVOICE_ZATCA_P2_LIVE_HOST set to that environment's ZATCA address. Confirm the address in the Fatoora portal before you add it.
3. Click Switch environment. When the line is in place, the page shows "wp-config.php has the required line."

Tip: In the sandbox, ZATCA issues a shared test certificate, so use the test VAT number 399999999900003 as your seller VAT in Phase 1 while you test.

#Step 2: Fill in the seller, device unit and tax mapping

Open Seller, device unit and tax mapping.

1. Seller: Registration scheme (CRN, MOM, MLS, 700, SAG or OTH), Registration number, Street, Building number (4 digits), District, City and Postal code (5 digits).
2. Device unit: Branch name, Common name, Serial number and Industry.
3. Invoice types: what this unit issues. 1100 is both B2B (Standard) and B2C (Simplified), 0100 is B2C only, 1000 is B2B only. The choice goes into the certificate, so changing it later needs a new onboarding.
4. Tax class mapping: map each WooCommerce tax class to a ZATCA Category: S - Standard rate, Z - Zero rated, E - Exempt or O - Not subject to VAT. Leave the Tax class slug empty for the standard class. Categories other than S need an Exemption reason.
5. Click Save Phase 2 settings.

#Step 3: Onboard with ZATCA

1. Get a 6-digit one-time code (OTP) from the Fatoora portal.
2. Under Onboard with ZATCA, enter it in One-time code (OTP) and click Onboard.
3. Wait and keep the page open. Onboarding sends several requests to ZATCA and can take a minute.

When it finishes, the card shows Onboarded, the certificate's Valid until date and how many days are left. The code is used once and is not stored. If onboarding fails, the message names the step that failed.

#Step 4: Switch on Phase 2

Turn on Switch on Phase 2 and confirm. From now on, new invoices are signed and sent to ZATCA. If something is missing, the card lists what to fix under "Phase 2 cannot be switched on yet".

#How invoices are handled

• Simplified (B2C): signed, given to the customer at once, and reported to ZATCA within 24 hours.
• Standard (B2B): an order with a buyer VAT number. It is sent for clearance and held until ZATCA clears it. The buyer can't download it and no email carries it until then. You can still open an internal copy labelled NOT CLEARED. After clearance, the PDF is rebuilt with the cleared QR code and released to the buyer, and the invoice email owed to them is sent once.

For Standard invoices, the buyer needs a VAT number and a Saudi address with building number and district. See Buyer VAT number.

#Follow up in the Invoices tab

The Invoices tab lists every Phase 2 document with its number, type, status and messages. Statuses include Pending, Reported, Waiting for clearance, Cleared, Not cleared, Rejected, Check in portal and Voided.

• Submit now / Clear now: send a waiting document right away.
• Send again: for a document in Check in portal. Check the Fatoora portal first; ZATCA may already have it.
• Void: close a document that can never be finished, with a reason. This cannot be undone.
• Retry release: release a cleared Standard document whose release to the buyer gave up.
• View PDF and Download PDF: open the document.
• Download XML (signed, or cleared by ZATCA): the XML file of the document.

#Certificates

Before the certificate expires, click Renew with OTP with a new code. Phase 2 can stay on. An expired certificate stops new invoices until it is renewed; documents already queued are still sent. Re-onboard replaces the credentials, for example after you change the invoice types.

Warning: Credentials are sealed with your site's secret keys in wp-config.php, or with VITE_INVOICE_ZATCA_KEY if you define it. Don't change them afterwards, or you will need to onboard again.