OTP (Fatoora portal one-time password)

By Matheel, from ZATCA's specifications and SDK 3.4.8 · Updated

The OTP is a one-time code the taxpayer generates in ZATCA's Fatoora portal to approve onboarding a device. It is valid for one hour.

The OTP is a one-time code that proves the taxpayer approves onboarding a device. The business owner logs in to the Fatoora portal (fatoora.zatca.gov.sa), chooses to onboard a new solution unit, and copies the code.

Where it goes: an otp header on the compliance CSID request (POST /compliance) and on production CSID renewal (PATCH /production/csids). The portal can generate up to 100 OTPs at once, each valid for one hour, so each device gets its own.

What goes wrong: the code expires before it is used, or a developer tries to onboard a customer's device without asking the customer for an OTP. The certificate is issued in the taxpayer's name, so plan this step with your first customer early. The developer portal needs no real OTP: it accepts a published test value.

On Matheel you send otp in the body of POST /api/v1/onboarding; on sandbox Matheel uses the test value for you. Merchants without a developer can type their OTP on their phone through an activation link.

Example

{"environment":"simulation","otp":"123456","seller":{"vat_number":"3…3","legal_name_ar":"…","crn":"…",
 "address":{"street":"…","building_number":"1234","district":"…","city":"Riyadh","postal_code":"12211"}}}

FAQ

How long is a ZATCA OTP valid?

One hour. The portal can generate up to 100 at once, one per device.

Do I need an OTP on the developer portal?

No. The developer portal accepts a published test value, and Matheel uses it automatically on sandbox.

Can I generate an OTP for my customer?

No. It comes from the taxpayer's own Fatoora account, so the business owner has to generate it and pass it to you.

Related terms

Let Matheel handle this for you

Matheel signs the invoice, files it with ZATCA and keeps the counter and hash in one request, and returns the PDF with the QR.

Try Matheel, no signup Matheel API docs