Fix rejected ZATCA invoices in WooCommerce

Raseedo records invoice status and ZATCA responses in your WooCommerce admin. When an invoice fails or stays pending, start with WooCommerce > ZATCA E-Invoicing > E-invoices.

This guide covers the common problems with onboarding, invoice reporting, certificates and customer invoice pages. Check the document's status and ZATCA response before changing settings.

Onboarding fails with an OTP error

What you see

The onboarding process stops after you enter the one-time password. Raseedo cannot complete the certificate process, so the store is not ready to issue invoices in the selected environment.

Why

The six-digit OTP may have expired. ZATCA OTPs are valid for one hour. A code that has already been used can also cause onboarding to fail.

Another possibility is an environment mismatch. You may be trying to use an OTP from a different onboarding environment.

The sandbox uses a prefilled test OTP. Simulation and Production require OTPs generated through the Fatoora portal.

Fix

Check the environment selected in WooCommerce > ZATCA E-Invoicing > Seller details. For Sandbox, use the test OTP supplied by Raseedo.

For Simulation or Production, sign in to fatoora.zatca.gov.sa. Generate a new six-digit OTP for onboarding a new solution unit.

Return to the Onboarding tab and enter the new code within one hour. Select Onboard this store again.

If the process fails during the compliance checks, record the displayed error before contacting support. The plugin must complete six compliance checks before receiving the production certificate.

ZATCA rejects an invoice

What you see

An invoice appears as rejected in the E-invoices tab. The WooCommerce order also contains a note with ZATCA's rejection information.

The invoice has not passed ZATCA's validation for that submission.

Why

A rejection can result from incorrect seller information, an invalid VAT number or address details that do not meet the requirements.

For example, a Saudi VAT number must contain 15 digits and start and end with 3. Seller details also include the legal name, commercial registration number, National Address short code and branch.

The specific cause depends on ZATCA's response for that document.

Fix

Open WooCommerce > ZATCA E-Invoicing > E-invoices and find the rejected document.

Read the reason returned by ZATCA. Use that response to identify which field or document information needs correction.

Open Seller details and check the relevant business information against your records. Correct the values identified by ZATCA.

A corrected document must then be issued. Do not assume that retrying the same rejected XML will resolve an error in its contents.

Keep the original rejection information for your records. If the reason is unclear, include the ZATCA response when contacting support.

Invoices remain pending

What you see

A paid WooCommerce order has an invoice, but its submission remains pending. The E-invoices tab does not show a completed ZATCA response for that document.

You may also see a Site Health warning about documents waiting too long.

Why

Raseedo creates simplified invoices and reports them in the background through WooCommerce's Action Scheduler. If WP-Cron or Action Scheduler is not running, scheduled submissions may remain in the queue.

Network problems and ZATCA outages can also delay reporting. Raseedo retries these submissions for hours, within the 24-hour reporting window.

Fix

Open WooCommerce > Status > Scheduled Actions.

Check whether scheduled tasks are running and whether there are failed or overdue actions. If the scheduler is not processing tasks, investigate the WP-Cron or Action Scheduler problem on your WordPress site.

Next, open the E-invoices tab and inspect the affected documents. Check whether Raseedo has recorded a ZATCA rejection or whether submission is still pending.

Avoid repeatedly creating replacement invoices while the original submission remains unresolved.

Simplified tax invoices must be reported to ZATCA within 24 hours. If a document is approaching that limit, investigate the queue and contact support with its status and available response.

Pro also includes bulk retry for e-invoices that could not be sent.

A certificate is expiring or has expired

What you see

WordPress Site Health reports that the e-invoicing certificate is approaching expiry. Raseedo begins warning you 30 days before the certificate expires.

You may also discover that the certificate has already expired.

Why

Raseedo signs invoices using the certificate obtained during ZATCA onboarding. The certificate has a validity period, so it must be renewed.

An expired certificate cannot be treated as a current signing certificate.

Fix

Open WooCommerce > ZATCA E-Invoicing and confirm the environment associated with your store. Sign in to the Fatoora portal and generate a new OTP for the relevant environment.

Return to the Onboarding tab. Enter the new OTP and complete onboarding again. Raseedo obtains the certificates through the onboarding process.

Check that onboarding completes and review the E-invoices tab afterward. If the certificate has already expired, investigate any affected documents before assuming they have been issued or reported successfully.

Onboarding is lost after a site migration

What you see

After moving your WordPress site or changing its configuration, Raseedo can no longer use the stored onboarding credentials. Previously issued invoices may still be present, but the current certificate and key are not available for signing new documents.

Why

Raseedo encrypts its certificates and private keys using the WordPress AUTH_KEY and SECURE_AUTH_KEY values. If those security keys change during a migration, the plugin cannot decrypt credentials that were encrypted using the old values.

Fix

Check whether AUTH_KEY or SECURE_AUTH_KEY changed during the migration. If the keys have changed, complete onboarding again using a new OTP for the selected environment.

You do not need to recreate previously issued invoices because of a security-key change. The plugin's existing signed XML documents and stored ZATCA responses are unaffected.

After onboarding, check the E-invoices tab and confirm that new documents are processing. Never send WordPress security keys, private signing keys or passwords to support.

A customer cannot open the invoice page

What you see

A customer reports that the invoice link does not open the expected invoice page. The order may have been completed and its invoice issued, but the customer cannot access it using the link they have.

Why

Raseedo provides an Arabic and English customer invoice page containing the QR code.

That page opens using the WooCommerce order key. The key must be present in the link used to access the invoice.

If a link is incomplete or its order key is missing, it may not open the intended invoice.

Fix

Open the affected WooCommerce order and confirm that its invoice has been issued.

Use the invoice link associated with the order instead of constructing a URL manually. Raseedo includes invoice links on the customer order page and in order emails.

Check that the complete link, including the order key, reaches the customer.

If the original link still fails, contact support with the order information and a description of the problem. Do not share the customer's order key publicly.

A QR code is not accepted by a scanner

What you see

A scanner does not accept the QR code, or the code contains fewer invoice fields than expected for a Phase 2 document. The customer may be looking at a QR code generated by another invoicing plugin.

Why

ZATCA Phase 2 invoices use a QR code containing TLV data, including cryptographic information. Raseedo's QR code includes the seller name, VAT number, date and time, invoice total, VAT amount, invoice hash and digital signature. A Phase 1 style QR code generated by another plugin may not contain the Phase 2 fields.

Fix

Open the customer invoice page generated by Raseedo for the affected order. Check that the invoice has a signed XML document and review its ZATCA status in the E-invoices tab.

Use the QR code from Raseedo's invoice page when checking that document. Do not substitute a QR code produced by another plugin.

If the Raseedo QR code is still rejected, record the scanner's reported error and the document's ZATCA response. Send those details to support so the problem can be investigated against the issued document.

Contact support with the document details

Email info@raseedo.com for setup problems, onboarding failures, rejected documents or invoice-page issues. Pro includes priority email support. There is no promised response time.

Include the following information:

1. Your WordPress version, WooCommerce version and Raseedo plugin version.
2. Which environment you are using: Sandbox, Simulation or Production.
3. The affected order or invoice reference and the status shown in the E-invoices tab.
4. The ZATCA response for the document, including the rejection reason if one is available.
5. A short description of what happened and which steps you have already tried.

Never email private keys, OTPs, passwords or WordPress security keys. Remove sensitive credentials from any information you send.

For installation and onboarding instructions, see the setup guide.