Fatoora sandbox, Simulation and Production environments explained

Fatoora has three environments: Sandbox for testing with sample data, Simulation for rehearsing with your VAT number, and Production for issuing legally valid invoices. You can test your WooCommerce connection before going live. Only invoices issued in Production count as legally issued tax invoices.

The three Fatoora environments compared

ZATCA operates separate environments for development, testing and live e-invoicing. Each has a different purpose, even though the invoice format and integration process are similar.

The important distinction is between testing an integration and issuing a tax invoice. A successful test response does not mean an invoice has been legally issued.

ZATCA's Fatoora Portal User Manual covers the Fatoora (Production) and Fatoora Simulation portals and their onboarding procedures. The Sandbox is part of ZATCA's separate Developer Portal.

The sandbox is for initial integration testing

The Sandbox belongs to ZATCA's Developer Portal. It lets developers test how an invoicing system communicates with Fatoora without using a taxpayer's Production account.

You work with test data rather than your business's registered VAT identity. The documents are examples used to check the integration. They have no legal effect as issued tax invoices.

How Raseedo handles sandbox onboarding

In Raseedo, select Sandbox under the environment setting. The plugin fills in the test OTP, so you do not need to generate a Production OTP for this step.

The onboarding process creates the signing key and certificate request. Raseedo then communicates with the selected ZATCA environment.

The plugin supports these document operations:

• Creating UBL 2.1 XML invoices.
• Applying the cryptographic signature.
• Generating the QR code.
• Submitting documents through the Fatoora API.
• Creating credit notes when an order is refunded.

Sandbox testing is useful when an agency is preparing a store or checking an integration before the store owner starts onboarding with their registered VAT details.

It is also a place to examine the resulting XML and responses before moving to a taxpayer-specific environment. A successful sandbox test confirms what was tested there. Simulation is an optional environment for end-to-end testing and is recommended before going live. Production onboarding is required to issue live invoices.

Simulation uses your registered VAT identity

Simulation is the rehearsal environment for a taxpayer preparing to issue live invoices. You use your registered VAT number and obtain the OTP through the Fatoora Simulation portal.

Unlike the Sandbox, Simulation uses your business identity. Unlike Production, documents submitted in Simulation are not legally issued tax invoices.

Getting a Simulation OTP

Open fatoora.zatca.gov.sa and access the Simulation portal using your taxpayer account.

The process is:

1. Open the Fatoora Simulation portal.
2. Choose the option to onboard a new solution unit or device.
3. Generate a six-digit OTP.
4. Select Simulation in Raseedo's environment setting.
5. Paste the OTP into Raseedo's Onboarding tab.
6. Start onboarding while the OTP is valid.

The OTP expires one hour after generation. Generate it when you are ready to complete onboarding rather than collecting it several hours beforehand.

Raseedo creates the key and certificate request, obtains the compliance certificate, passes six sample-document checks and obtains the certificate used for the selected environment.

ZATCA confirms that its Simulation and Production portals are independent and that devices must be onboarded separately. See the Fatoora Portal User Manual.

What to check in Simulation

Use Simulation to rehearse the invoice process with your business details. For a WooCommerce store, review how paid orders become signed invoices, how those invoices appear in the E-invoices tab, and how refunds produce credit notes referencing the original documents.

Also check the information that appears on customer invoice pages. Raseedo provides bilingual Arabic and English invoice pages with QR codes, accessible through order pages and order emails.

If ZATCA rejects a document, review the returned reason in WooCommerce > ZATCA E-Invoicing > E-invoices. Simulation is the appropriate place to identify these issues before sending live documents.

Production is for live tax invoices

Production is the environment used when your store is ready to issue invoices under ZATCA's Phase 2 requirements.

You must onboard with a Production OTP obtained from the Fatoora portal. A Simulation certificate does not replace Production onboarding.

In Production, Raseedo's free plugin creates a simplified tax invoice for each paid order in Saudi riyals (SAR). Orders in other currencies are skipped, with an order note and a Site Health warning. For eligible orders, the plugin signs the XML with the store's certificate, generates the QR code and reports the document to ZATCA in the background.

Simplified invoices must be reported within 24 hours. Raseedo uses WooCommerce Action Scheduler for submission and retries network failures and ZATCA outages for hours within that reporting window.

Standard B2B invoices have a different requirement. They must be cleared by ZATCA before the buyer receives them. Raseedo Pro adds this process for orders with a valid buyer VAT number.

ZATCA describes the Phase 2 integration requirement on its e-invoicing page.

The deadline matters

ZATCA's Wave 25 covers businesses whose VAT-subject revenue exceeded SAR 187,500 in any of 2022, 2023, 2024 or 2025. Those businesses must integrate with Fatoora by 1 February 2027.

ZATCA notifies targeted taxpayers at least six months before their integration date. If your business is included, complete your tests and Production onboarding before the deadline.

Source: ZATCA Wave 25 announcement, 24 July 2026.

A WooCommerce store can follow this testing order

The suggested order is Sandbox, Simulation and then Production. An agency can handle the early testing while the store owner prepares the taxpayer account details.

Step 1. Prepare the store

Raseedo requires WordPress 6.5 or later, PHP 8.1 or later and an active WooCommerce installation.

Open WooCommerce > ZATCA E-Invoicing > Seller details. Fill in all 11 required fields: legal seller name, VAT number, seller ID number (usually the commercial registration number), street, building number, district, city, postal code, National Address short code, branch name and business category. Onboarding cannot start in any environment, including Sandbox, until all 11 fields are filled.

Step 2. Start with Sandbox

Select Sandbox and complete the initial onboarding process with the test OTP. Turn on "Issue e-invoices" to test paid orders in Sandbox. Review the resulting invoices and any ZATCA responses.

Step 3. Rehearse in Simulation

Select Simulation and onboard using a new OTP from the Simulation portal. Turn on "Issue e-invoices" to test paid orders in Simulation. Review paid-order invoices, refund credit notes and the seller details included in the documents.

Step 4. Onboard in Production

Select Production and generate a new OTP in the Production Fatoora portal. Complete onboarding for that environment.

Turn on "Issue e-invoices" in Production only when your store is ready to issue live invoices for paid orders.

Your pre-launch checklist

• WordPress, PHP and WooCommerce meet the plugin requirements.
• The legal seller name is correct.
• The VAT number has 15 digits and starts and ends with 3.
• All 11 Seller details fields are filled: legal seller name, VAT number, seller ID number (usually the commercial registration number), street, building number, district, city, postal code, National Address short code, branch name and business category. Onboarding is blocked in every environment, including Sandbox, until they are complete.
• Sandbox testing is complete.
• Simulation onboarding and document checks are complete if you chose to use this optional, recommended testing environment.
• Production onboarding uses a new Production OTP.
• The Production certificate has been obtained.
• "Issue e-invoices" was turned on for paid-order testing in Sandbox and Simulation, and is turned on in Production only when the store is ready to issue live invoices.
• The E-invoices tab is checked for submission results.

For the plugin setup process, follow the Raseedo setup guide.

Common onboarding mistakes can be avoided

Using a Production OTP in Simulation

Simulation and Production use independent onboarding environments. An OTP generated for Production should not be used for Simulation onboarding.

Check which environment is selected in Raseedo before generating the code. Generate the OTP in the matching Fatoora portal.

Using an expired OTP

A Fatoora OTP is valid for one hour. If the code has expired, generate another one and repeat onboarding.

Do not repeatedly submit an old code after its validity period has ended.

Entering incorrect seller information

Your VAT number and legal business information need to match the taxpayer details used for onboarding. Raseedo checks the VAT number format, including its 15-digit length and the first and last digits.

Review the Seller details tab before requesting a new OTP. If ZATCA returns an error, read the response before repeating the request.

Treating a test invoice as a live invoice

Sandbox and Simulation documents are for testing. They cannot replace invoices that must be issued in Production.

Keep this distinction in mind when reviewing test orders. The presence of XML, a signature or a QR code does not change the environment in which the document was created.

Check your Production records after onboarding

Raseedo stores signed XML files and ZATCA responses on your own WordPress site. You can review the document records through the E-invoices tab.

Site Health also warns when e-invoicing is enabled without completed onboarding, when documents have waited too long, or when a certificate is approaching expiry.

Raseedo warns 30 days before certificate expiry. Renewal requires onboarding again with a new OTP. Your previously issued invoices are not affected by changes to the stored onboarding keys.