> ## Documentation Index
> Fetch the complete documentation index at: https://invopop-zatca-valid-identities.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ZATCA supplier registration in Saudi Arabia

> Onboard a Saudi VAT-registered party with ZATCA and provision its production CSID.

<Note>
  Registration is required for any Saudi VAT number that will clear or report invoices through Invopop. It is a prerequisite for the [clearance and reporting](/guides/sa-zatca-clearance-reporting) flow.
</Note>

## Sandbox environments

In sandbox, the **Register Party** step's configuration selects which ZATCA portal to onboard against. Production enrollments ignore this and always use the live endpoint.

| Mode                   | Target                           | OTP in the wizard                                                           | Use it to                                                                                             |
| ---------------------- | -------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `developer`            | ZATCA Developer (sandbox) portal | **Dummy** — any placeholder value is accepted                               | Test the onboarding flow end to end without touching a real ZATCA account.                            |
| `simulation` (default) | ZATCA Simulation portal          | **Real** — must be generated from the supplier's FATOORA Simulation account | Rehearse the production onboarding with genuine certificates and compliance checks before going live. |

The two modes target different ZATCA sandbox endpoints and differ mainly in how the OTP is treated:

* **Developer** is the lightweight sandbox. ZATCA does not validate the OTP, so the value the supplier types in the [onboarding wizard](#the-onboarding-wizard) is a dummy.

  You can **register any party** in developer mode, but ZATCA only accepts **invoices issued from its fixed test VAT number, `399999999900003`**.
* **Simulation** mirrors production. The OTP must be a **real** one-time password the supplier generates from their FATOORA *Simulation* portal, exactly as they would in production.

<Note>
  In both sandbox modes the supplier still completes the same wizard, only the OTP requirement changes.
</Note>

## How it works

Registration spans two parts: a workflow you run against the party document, and a hosted onboarding wizard the supplier completes to provide the FATOORA OTP.

<Frame caption="ZATCA register supplier">
  <img src="https://mintcdn.com/invopop-zatca-valid-identities/eNpvg-cG5qwcubVA/assets/guides/sa-register-supplier.png?fit=max&auto=format&n=eNpvg-cG5qwcubVA&q=85&s=2f554d26a319b387aa1c5271404eff3f" width="640" data-path="assets/guides/sa-register-supplier.png" />
</Frame>

<Steps>
  <Step title="Set State → Processing">
    Sets the state of the silo entry as "Processing".
  </Step>

  <Step title="Register supplier with ZATCA">
    Validates the party's tax ID, [supplier identity](#multi-branch-entities), and full address, stakes the claim on that VAT number and identity, then publishes a public onboarding link in the meta section of the party. The supplier follows this link to complete the onboarding wizard.
  </Step>

  <Step title="Wait for ZATCA certificate upload">
    Pauses until the supplier uploads the compliance CSID. It will then submit the mandatory compliance sample invoices and swaps the Compliance CSID with the Production CSID.
  </Step>

  <Step title="Set State → Registered">
    Sets the state of the silo entry as "Registered".
  </Step>
</Steps>

<Tabs>
  <Tab title="Template">
    <Card iconType="duotone" title="ZATCA register party workflow" icon="code-branch" href="https://console.invopop.com/redirect/workflows/new?template=sa-sa-register" cta="Add to my workspace">
      Publishes the ZATCA onboarding link and provisions the party's production CSID.
    </Card>
  </Tab>

  <Tab title="Code">
    Copy and paste into a new [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party).

    ```json Register supplier in ZATCA theme={null} theme={"system"}
    {
        "name": "ZATCA register supplier",
        "description": "",
        "schema": "org/party",
        "steps": [
            {
                "id": "f60b2e30-6fce-11f1-b09d-79f60b032746",
                "name": "Set state",
                "provider": "silo.state",
                "summary": "Set state to `processing`{.state .processing}",
                "config": {
                    "state": "processing"
                }
            },
            {
                "id": "fd448bb0-6fce-11f1-b09d-79f60b032746",
                "name": "Register supplier with ZATCA",
                "provider": "gov-sa.party.register",
                "summary": "Developer Portal",
                "config": {
                    "mode": "developer"
                }
            },
            {
                "id": "0064b770-6fcf-11f1-b09d-79f60b032746",
                "name": "Wait for ZATCA OTP authorization",
                "provider": "gov-sa.wait.authorization"
            },
            {
                "id": "0236df60-6fcf-11f1-b09d-79f60b032746",
                "name": "Set state",
                "provider": "silo.state",
                "summary": "Set state to `registered`{.state .registered}",
                "config": {
                    "state": "registered"
                }
            }
        ],
        "rescue": [
            {
                "id": "04aa0240-6fcf-11f1-b09d-79f60b032746",
                "name": "Set state",
                "provider": "silo.state",
                "summary": "Set state to `error`{.state .error}",
                "config": {
                    "state": "error"
                }
            }
        ]
    }
    ```
  </Tab>
</Tabs>

## The onboarding wizard

The link published by **Register Party** provides an onboarding wizard for the supplier to complete:

<Steps>
  <Step title="Company details">
    <Frame caption="Company details screen">
      <img src="https://mintcdn.com/invopop-zatca-valid-identities/eNpvg-cG5qwcubVA/assets/guides/sa-wizard-1.png?fit=max&auto=format&n=eNpvg-cG5qwcubVA&q=85&s=4f9ad40b987b52931d97e12b5ba2a3b8" width="640" data-path="assets/guides/sa-wizard-1.png" />
    </Frame>

    The supplier confirms the legal name and provides the **invoice type** (`1000` standard, `0100` simplified, or `1100` both), **branch name**, **registered address**, and **business category**. These values feed the certificate request.
  </Step>

  <Step title="Get the OTP from FATOORA">
    <Frame caption="FATOORA instructions screen">
      <img src="https://mintcdn.com/invopop-zatca-valid-identities/Zeu21Kx-veeFkn7G/assets/guides/sa-wizard-2.png?fit=max&auto=format&n=Zeu21Kx-veeFkn7G&q=85&s=f7eb7ea40cdafacf2387c0e4995e1380" width="640" data-path="assets/guides/sa-wizard-2.png" />
    </Frame>

    The supplier signs in to the FATOORA portal and generates a One-Time Password for the EGS unit. The wizard shows the relevant FATOORA screens.
  </Step>

  <Step title="Enter the OTP">
    <Frame caption="OTP Code screen">
      <img src="https://mintcdn.com/invopop-zatca-valid-identities/Zeu21Kx-veeFkn7G/assets/guides/sa-wizard-3.png?fit=max&auto=format&n=Zeu21Kx-veeFkn7G&q=85&s=cc3ed5c4c0250c45c00443cba9601eba" width="640" data-path="assets/guides/sa-wizard-3.png" />
    </Frame>

    The supplier pastes the OTP and reviews the recap of the details that will be sent to ZATCA.
  </Step>

  <Step title="Confirm details">
    <Frame caption="Confirmation screen">
      <img src="https://mintcdn.com/invopop-zatca-valid-identities/Zeu21Kx-veeFkn7G/assets/guides/sa-wizard-4.png?fit=max&auto=format&n=Zeu21Kx-veeFkn7G&q=85&s=87b26024dca9a54906f0ac3eaada179c" width="640" data-path="assets/guides/sa-wizard-4.png" />
    </Frame>

    Here you will make sure all the details you entered were correct. Click "Back" if you need to change anything.
  </Step>

  <Step title="Submit">
    <Frame caption="Submission screen">
      <img src="https://mintcdn.com/invopop-zatca-valid-identities/Zeu21Kx-veeFkn7G/assets/guides/sa-wizard-5.png?fit=max&auto=format&n=Zeu21Kx-veeFkn7G&q=85&s=60bb3dcf63e9f8386d90e79740f8db75" width="640" data-path="assets/guides/sa-wizard-5.png" />
    </Frame>

    Upon submit, Invopop requests the **Compliance CSID**, and stores the credentials. This unblocks the **Wait for Authorization** step in the workflow.
  </Step>
</Steps>

<Info>
  The invoice type chosen here determines which compliance samples Invopop submits: `1000` runs standard tax invoices, credit notes, and debit notes; `0100` runs the simplified equivalents; `1100` runs both sets.
</Info>

## Unregistration (sandbox only)

Unregistering a party from ZATCA in production environment is handled by the **tax payers**, directly in the **FATOORA portal**, signing in with their own credentials.

Invopop also provides an unregister action that removes the party and its stored credentials from **Invopop's internal systems only**. It does not touch the party's registration with ZATCA. It targets a single registration, the one that matches the party's VAT number and [supplier identity](#multi-branch-entities), so unregistering one branch leaves the other registrations under the same VAT number untouched.

<Warning>
  This action is intended for **testing in sandbox**, for example to re-onboard the same VAT number and identity during development. It is **not** for live environments; unregistering at ZATCA is always done by the tax payer in the FATOORA portal.
</Warning>

<Tabs>
  <Tab title="Template">
    <Card iconType="duotone" title="ZATCA unregister supplier workflow (sandbox only)" icon="code-branch" href="https://console.invopop.com/redirect/workflows/new?template=sa-sa-unregister" cta="Add to my workspace">
      Removes the party's registration and stored credentials from Invopop's internal systems.
    </Card>
  </Tab>

  <Tab title="Code">
    Copy and paste into a new [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party).

    ```json Unregister supplier in ZATCA theme={null} theme={"system"}
    {
        "name": "ZATCA unregister supplier",
        "description": "Removes a supplier's registration from Invopop's internal systems",
        "schema": "org/party",
        "steps": [
            {
                "id": "572ac450-6fcf-11f1-b09d-79f60b032746",
                "name": "Set state",
                "provider": "silo.state",
                "summary": "Set state to `processing`{.state .processing}",
                "config": {
                    "state": "processing"
                }
            },
            {
                "id": "5c0e9910-6fcf-11f1-b09d-79f60b032746",
                "name": "Unregister supplier from ZATCA",
                "provider": "gov-sa.party.unregister"
            },
            {
                "id": "5e800e40-6fcf-11f1-b09d-79f60b032746",
                "name": "Set state",
                "provider": "silo.state",
                "summary": "Set state to `void`{.state .void}",
                "config": {
                    "state": "void"
                }
            }
        ],
        "rescue": [
            {
                "id": "60e4d940-6fcf-11f1-b09d-79f60b032746",
                "name": "Set state",
                "provider": "silo.state",
                "summary": "Set state to `error`{.state .error}",
                "config": {
                    "state": "error"
                }
            }
        ]
    }
    ```
  </Tab>
</Tabs>

## Multi-branch entities

A business can run several branches that all share the same VAT number while each branch onboards its own device or system. A single VAT number therefore often needs more than one registration, and Invopop supports this through the GOBL identities field.

Every party registered with ZATCA is linked to a unique CSID certificate that identifies both its VAT number and its branch. Invopop gives each unique combination of VAT number and supplier identity its own CSID certificate, allowing them to act independently and through their own invoice chain.

Set the identity on the [`org.Party`](https://docs.gobl.org/draft/org/party) document as an entry in `identities` whose `type` is one of:

| `type` | Identity                                                             |
| ------ | -------------------------------------------------------------------- |
| `CRN`  | Commercial Registration Number                                       |
| `MOM`  | Momrah license (Ministry of Municipality, Rural Affairs and Housing) |
| `MLS`  | MLSD license (Ministry of Human Resources and Social Development)    |
| `700`  | 700 number (unified national number)                                 |
| `SAG`  | Sagia license (Ministry of Investment, formerly SAGIA)               |
| `OTH`  | Other identifier                                                     |

## FAQ

<AccordionGroup>
  <Accordion title="What do I need to onboard a party with ZATCA?">
    A workspace with the **Saudi Arabia** app enabled, and an `org/party` (the supplier) carrying:

    * a Saudi **VAT registration number**,
    * an **identity** of type `CRN`, `MOM`, `MLS`, `700`, `SAG`, or `OTH`, and
    * a complete **national address** (building number, postal code, district, street, additional street, and country).

    During the hosted onboarding wizard the supplier also provides the legal name, invoice type (`1000` standard / `0100` simplified / `1100` both), branch name, registered address, and business category — plus the FATOORA OTP.
  </Accordion>

  <Accordion title="How long is the OTP valid?">
    **1 hour** from when it is generated in the FATOORA portal. If it expires, generate a new one and re-enter it in the wizard.
  </Accordion>

  <Accordion title="What is the difference between Developer and Simulation sandbox modes?">
    In **Developer** mode the OTP is not validated (any placeholder works) and you can only send invoices from ZATCA's fixed test VAT `399999999900003`. In **Simulation** mode the OTP must be real and you can send from any registered party.
  </Accordion>

  <Accordion title="Can I test in Simulation without a real FATOORA account?">
    No. Simulation requires a real FATOORA account and taxpayer to generate a valid OTP. Use **Developer** mode if you want to test the flow without a real account.
  </Accordion>
</AccordionGroup>

More available in our [Saudi Arabia FAQ](/faq/saudi-arabia) section.

***

<AccordionGroup>
  <Accordion title="🇸🇦 Invopop resources for Saudi Arabia">
    |            |                                                                                                                                                                                                                                               |
    | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Compliance | <Icon icon="https://assets.invopop.com/flags/sa.svg" /> [Invoicing compliance in Saudi Arabia](/compliance/saudi-arabia)<br /> <Icon icon="timeline" /> [Compliance timeline](/timelines/saudi-arabia)                                        |
    | Apps       | <Icon icon="https://assets.invopop.com/flags/sa.svg" /> [Saudi Arabia](/apps/saudi-arabia)                                                                                                                                                    |
    | Guides     | <Icon icon="book" /> [Registration](/guides/sa-zatca-registration)<br /><Icon icon="book" /> [Clearance & Reporting](/guides/sa-zatca-clearance-reporting)                                                                                    |
    | FAQ        | <Icon icon="square-question" /> [Saudi Arabia FAQ](/faq/saudi-arabia)                                                                                                                                                                         |
    | GOBL       | <Icon icon="https://assets.invopop.com/icons/gobl.svg" /> [Saudi Arabia Tax Regime](https://docs.gobl.org/regimes/sa)<br /> <Icon icon="https://assets.invopop.com/icons/gobl.svg" /> [ZATCA Addon](https://docs.gobl.org/addons/sa-zatca-v1) |
    | GitHub     | <Icon icon="github" /> [gobl.sa.zatca](https://github.com/invopop/gobl.sa.zatca)                                                                                                                                                              |
  </Accordion>
</AccordionGroup>

<Card title="Participate in our community" icon="forumbee" href="https://community.invopop.com" arrow="true" horizontal>
  Ask and answer questions about invoicing in Saudi Arabia →
</Card>