Marketplace integration workflow: from seller registration to ZATCA response
One buyer, two sellers, two invoices. This page shows the complete flow for a multi-seller marketplace: device registration, invoices, ZATCA responses and credit notes.
One marketplace, many sellers, one integration
FatooraConnect sits between your marketplace and ZATCA: the marketplace sends invoice data to FatooraConnect, FatooraConnect signs it and submits it to ZATCA, and the ZATCA response goes back to the marketplace.
In a marketplace each seller is a separate taxpayer. Each seller is therefore registered with ZATCA once (device registration), and every order is split into one invoice per seller. This page walks through that full workflow, from device registration to the response your marketplace receives.
https://api.fatooraconnect.com/v1The scenario
One buyer checks out a single cart containing products from two sellers. ZATCA receives two invoices, and the buyer receives two invoices, each carrying a different seller's details.
Seller A
iPhone 13
- Seller A name, VAT number and address on the invoice
- Signed with Seller A's ZATCA device certificate
Seller B
iPhone 15
- Seller B name, VAT number and address on the invoice
- Signed with Seller B's ZATCA device certificate
Same buyer and same marketplace order number on both invoices.
Who does what
The marketplace holds one FatooraConnect account and one API key; each seller is one ZATCA device inside that account.
Seller (A, B, ...)
Taxpayer and legal issuer of the invoiceGenerates a 6-digit OTP in ZATCA's Fatoora portal and gives it to the marketplace, once, at registration.
Marketplace
Your platformRegisters one device per seller, splits each order by seller, sends one invoice request per seller, stores the response and shows the invoice and QR to the buyer.
FatooraConnect
Integration layer (API and portal)Checks the data, builds the UBL XML, signs it with that seller's certificate, submits to ZATCA, returns the result, keeps the invoice history and logs.
ZATCA
Tax authorityIssues the device certificates, then clears or reports every invoice and returns warnings or errors.
The marketplace never talks to ZATCA directly and never handles certificates or private keys. FatooraConnect stores them encrypted and uses them only to sign that seller's invoices.
End-to-end flow
Registration (steps 1 to 5) happens once per seller. Steps 6 to 9 happen for every seller in every order, so the two-seller order makes two round trips to ZATCA and returns two responses.
Device registration
Each seller is registered with ZATCA one time, from the marketplace, with a single API call. The call returns a device_id; the marketplace saves it against that seller and uses it on every invoice for that seller.
One-time account setup (marketplace)
- Create the FatooraConnect account and complete the company profile.
- Create an API key in the portal under API keys. A test key (
ff_test_...) works with sandbox and simulation devices; a live key (ff_live_...) works with production devices. - Top up the wallet before going live. Production invoices are charged per accepted invoice; sandbox and simulation are free.
Per-seller registration
- The seller logs in to ZATCA's Fatoora portal and generates a 6-digit OTP. It expires within an hour.
- The seller enters the OTP in the marketplace's seller onboarding screen, together with their tax details.
- The marketplace calls
POST /v1/deviceswith the OTP and the seller's details. - FatooraConnect runs ZATCA's full onboarding for that seller. It takes up to a minute:
- generates the seller's private key and certificate request (CSR)
- sends the CSR and OTP to ZATCA and receives the compliance certificate (compliance CSID)
- submits six compliance test documents: standard and simplified, each as invoice, credit note and debit note
- requests and receives the production certificate (production CSID)
- FatooraConnect returns the
device_id. The marketplace stores it on the seller record.
Nothing is saved unless every step succeeds, so a failed registration can simply be repeated with a new OTP.
The flow runs once for Seller A and once for Seller B. A failure at either check saves nothing, so the marketplace can simply call again.
Fields the marketplace sends
| Field | Required | Meaning |
|---|---|---|
name | Yes | Your own label for the device, for example the seller's shop name |
environment | Yes | sandbox, simulation or production |
otp | Simulation and production | 6-digit OTP from the seller's Fatoora portal. Not needed for sandbox |
company_name | Yes | Seller's legal name, exactly as on the VAT certificate |
vat_number | Yes | 15 digits, starting and ending with 3 |
cr_number | Yes | Commercial registration number, 10 digits |
street | Yes | Street of the registered address |
building_number | Yes | 4 digits, from the national address |
plot_number | Yes | Additional number, 4 digits |
district | Yes | District |
city | Yes | City |
postal_code | Yes | 5 digits |
industry | No | Business sector. Defaults to Services |
These details go into the seller's ZATCA certificate and onto every invoice that device signs, so they cannot be changed afterwards. If a seller's VAT details change, register a new device for that seller.
Example: registering Seller A
{
"name": "Seller A - Main store",
"environment": "simulation",
"otp": "482913",
"company_name": "Seller A Trading Est.",
"vat_number": "310000000000003",
"cr_number": "1010000001",
"street": "King Fahd Road",
"building_number": "1234",
"plot_number": "5678",
"district": "Al Olaya",
"city": "Riyadh",
"postal_code": "12211",
"industry": "Trading"
}{
"device_id": "9b2f6c1e-4a7d-4f0b-8c3e-1d5a7e9f2b64",
"name": "Seller A - Main store",
"environment": "simulation",
"status": "active",
"company_name": "Seller A Trading Est.",
"vat_number": "310000000000003",
"cr_number": "1010000001",
"invoices_submitted": 0,
"registered_at": "2026-10-03T10:15:00+03:00"
}Seller B is registered the same way with Seller B's OTP and details, and gets a different device_id. The values above are illustrative.
Marketplace sends invoice data to FatooraConnect
When the buyer pays, the marketplace groups the cart lines by seller and sends one POST /v1/invoices request per seller. The device_id in each request decides which seller appears on the invoice; seller details are not sent again.
How the order is split
| Request 1 | Request 2 | |
|---|---|---|
device_id | Seller A's device | Seller B's device |
number | ORD-1001-A | ORD-1001-B |
uuid | New UUID | Another new UUID |
| Lines | iPhone 13, 1 x SAR 2,000.00 | iPhone 15, 1 x SAR 3,500.00 |
| VAT 15% | SAR 300.00 | SAR 525.00 |
| Total with VAT | SAR 2,300.00 | SAR 4,025.00 |
Prices are illustrative. Three rules matter for a marketplace:
- Invoice numbers must be unique across the whole marketplace account, not just per seller. A suffix or prefix per seller on the order number works well.
- Every invoice needs its own UUID, created by the marketplace. The same UUID cannot be reused for another invoice number.
- The two requests are independent. They can be sent in parallel, and one can succeed while the other fails.
Fields in the invoice request
| Field | Required | Meaning |
|---|---|---|
device_id | Yes | The seller's device from Step 1 |
number | Yes | Invoice number, up to 50 characters, unique in the account |
uuid | Yes | Unique ID of this invoice |
type | Yes | invoice, credit_note or debit_note |
category | Yes | simplified for a consumer buyer (B2C), standard for a business buyer (B2B) |
issued_at | No | Issue date and time. Defaults to now. Cannot be in the future |
supply_date | No | Date of supply. Defaults to the issue date |
buyer | Standard only | Name, VAT or CR number, street, building number, city, postal code. Optional for simplified |
lines[] | Yes | name, quantity, unit_price, optional discount, vat_category (S, Z, E, O), vat_rate (15, 5 or 0). Up to 200 lines |
total_without_vat | Yes | Sum of the lines after discount, before VAT |
total_vat | Yes | Sum of the VAT of the lines |
total_with_vat | Yes | Amount the buyer pays to this seller |
FatooraConnect recalculates the totals from the lines. If the marketplace's totals differ by more than 0.01, the request is refused and nothing is sent to ZATCA.
Example: Seller A's invoice for the iPhone 13
{
"device_id": "9b2f6c1e-4a7d-4f0b-8c3e-1d5a7e9f2b64",
"number": "ORD-1001-A",
"uuid": "3f0c9a52-7d1b-4e86-a2c4-5b8e1f6d9a01",
"type": "invoice",
"category": "simplified",
"buyer": { "name": "Ahmed Ali" },
"lines": [
{ "name": "iPhone 13", "quantity": 1, "unit_price": 2000.00,
"vat_category": "S", "vat_rate": 15 }
],
"total_without_vat": 2000.00,
"total_vat": 300.00,
"total_with_vat": 2300.00
}The request for Seller B is identical in shape: Seller B's device_id, number ORD-1001-B, a new uuid, the iPhone 15 line and its totals (3,500.00 / 525.00 / 4,025.00).
FatooraConnect signs and submits to ZATCA
For each request FatooraConnect does the following in one synchronous call, so the marketplace gets ZATCA's answer in the same HTTP response.
- Checks the API key, the rate limit and that the
device_idbelongs to the account. - Validates every field and recalculates the totals.
- Reserves the invoice number and charges the wallet in one transaction. A number ZATCA already accepted is returned as it is and never charged twice.
- Takes the seller's next invoice counter and previous invoice hash. ZATCA requires an unbroken chain per device, so invoices of one seller are processed one at a time; different sellers run in parallel.
- Builds the UBL 2.1 XML with that seller's name, VAT number and address from the device.
- Signs the XML with the seller's private key and certificate, and generates the QR code.
- Sends it to ZATCA:
- simplified (B2C) invoices go to the reporting endpoint and come back as REPORTED
- standard (B2B) invoices go to the clearance endpoint and come back as CLEARED, with ZATCA's own stamp and QR in the returned XML
- Stores the result. If ZATCA accepts, the charge stays. If ZATCA rejects or cannot be reached, the charge is refunded automatically.
The two-seller order runs this flow twice, once with each seller's device. If the wallet balance is too low at the charge step, the call returns 402 and nothing is sent to ZATCA.
ZATCA response goes back to the marketplace
The marketplace receives one JSON response per invoice. The status field and the HTTP code tell it what happened.
status | HTTP | Meaning | Marketplace action |
|---|---|---|---|
| REPORTED | 200 | ZATCA accepted a simplified invoice | Save uuid, hash, qr; show the invoice to the buyer |
| CLEARED | 200 | ZATCA cleared a standard invoice | Same, and download the cleared XML |
| REJECTED | 422 | ZATCA refused the invoice | Read error and zatca.errors, fix the data, send again |
| FAILED | 503 | ZATCA could not be reached or signing failed | Nothing was charged. Retry the same number later |
Example: response for Seller A's invoice
{
"status": "REPORTED",
"number": "ORD-1001-A",
"type": "invoice",
"category": "simplified",
"environment": "simulation",
"uuid": "3f0c9a52-7d1b-4e86-a2c4-5b8e1f6d9a01",
"issued_at": "2026-10-03T10:20:00+03:00",
"billing_reference": null,
"total_discount": 0,
"total_without_vat": 2000,
"total_vat": 300,
"total_with_vat": 2300,
"hash": "(invoice hash)",
"qr": "(base64 QR data)",
"charged": 0,
"error": null,
"zatca": { "warnings": [], "errors": [] },
"duplicate": false
}What the marketplace does with it
- Print the
qrvalue as a QR code on the buyer's invoice for that seller. The buyer ends up with two invoices and two QR codes. - Keep
uuidandnumber. They are needed later for a credit note if the buyer returns one of the phones. - Fetch the signed XML when needed with
GET /v1/invoices/{number}/xml. It exists only for accepted invoices. - Check any invoice again at any time with
GET /v1/invoices/{number}. zatca.warningscan be filled even on an accepted invoice. Log them; they do not block the invoice.duplicate: truemeans this number was already accepted earlier and the stored result was returned without a new submission or charge.
Credit notes
A return or refund is a credit note issued by the same seller that issued the original invoice. If the buyer returns only the iPhone 15, the marketplace sends one credit note with Seller B's device_id; Seller A's invoice stays as it is.
The credit note follows the same path as an invoice: marketplace to FatooraConnect, FatooraConnect to ZATCA, and the response back. The only addition is the reference to the original invoice, which FatooraConnect checks before anything is sent.
Fields in the credit note request
The body is the same as an invoice, sent to POST /v1/credit-notes, plus three fields.
| Field | Required | Meaning |
|---|---|---|
device_id | Yes | The device of the seller who issued the original invoice |
number | Yes | A new number for the credit note. It cannot be the original invoice number |
uuid | Yes | A new UUID for the credit note. It cannot be the original invoice UUID |
invoice_no | Yes | Number of the original invoice being corrected |
invoice_uuid | Yes | UUID of the original invoice, as returned in Step 4 |
reason | Yes | Why the note is issued, for example Goods returned. ZATCA requires it |
category | Yes | Same category as the original invoice: simplified or standard |
lines[] and totals | Yes | Only what is being credited, as positive amounts |
Example: buyer returns the iPhone 15
{
"device_id": "(Seller B's device_id)",
"number": "CN-1001-B",
"uuid": "c81d4e2e-bcf2-4a5d-9b1a-7e2f0d6c3a45",
"category": "simplified",
"invoice_no": "ORD-1001-B",
"invoice_uuid": "(uuid of ORD-1001-B)",
"reason": "Goods returned",
"buyer": { "name": "Ahmed Ali" },
"lines": [
{ "name": "iPhone 15", "quantity": 1, "unit_price": 3500.00,
"vat_category": "S", "vat_rate": 15 }
],
"total_without_vat": 3500.00,
"total_vat": 525.00,
"total_with_vat": 4025.00
}{
"status": "REPORTED",
"number": "CN-1001-B",
"type": "credit_note",
"billing_reference": {
"invoice_no": "ORD-1001-B",
"invoice_uuid": "(uuid of ORD-1001-B)",
"reason": "Goods returned"
},
"total_with_vat": 4025,
"qr": "(base64 QR data)",
"error": null,
"zatca": { "warnings": [], "errors": [] }
}The response has the same shape as an invoice response, with type set to credit_note and the reference filled in.
Rules FatooraConnect checks before sending
- The original invoice must have been accepted by ZATCA. A rejected or failed invoice cannot be credited (
reference_not_accepted). invoice_uuidmust match the UUID held forinvoice_no(reference_mismatch).invoice_nomust point at an invoice, not at another credit or debit note (reference_not_invoice).- An original invoice issued by another system before the marketplace joined FatooraConnect is accepted as sent.
Common cases
| Case | What the marketplace sends |
|---|---|
| Full return of one seller's item | One credit note for that seller with the full line and totals |
| Partial refund or price reduction | One credit note for that seller with only the refunded quantity or amount |
| Whole order cancelled | Two credit notes, one per seller, each against its own invoice |
| Extra charge after the invoice | A debit note: same body, sent to POST /v1/debit-notes |
A credit note is fetched later with GET /v1/credit-notes/{number} and its signed XML with GET /v1/credit-notes/{number}/xml. In production it is charged like an invoice, only when ZATCA accepts it.
Error handling and retries
Every error is JSON with a code the marketplace software can test and a message it can show to a person. Because each seller's invoice is a separate request, a failure affects only that seller's invoice.
One seller succeeds, the other fails
If Seller A's invoice is REPORTED and Seller B's is REJECTED, Seller A's invoice is final and is not sent again. The marketplace corrects Seller B's data and resends only ORD-1001-B. Resending an accepted number is safe: it returns the stored result with duplicate: true and no new charge.
Common errors
code | HTTP | What to do |
|---|---|---|
unauthorized | 401 | The API key is missing, wrong or revoked |
insufficient_balance | 402 | Top up the wallet, then send the invoice again |
company_suspended | 403 | Contact FatooraConnect support |
device_not_found | 404 | Wrong device_id, or a test key used with a production device |
invoice_in_progress | 409 | The same number is being submitted now. Wait, then fetch it with GET |
uuid_already_used | 409 | This uuid belongs to another invoice number. Create a new UUID |
seller_details_missing | 422 | Send the missing seller details when registering the device |
zatca_onboarding_failed | 422 | ZATCA refused the registration, usually a wrong or expired OTP. Ask the seller for a new OTP |
device_disabled | 422 | The seller's device was disabled in the portal |
| (validation) | 422 | A field is missing or invalid. The body lists the problem per field |
device_busy / rate_limited | 429 | Wait a few seconds (Retry-After), then retry |
zatca_unreachable | 503 | ZATCA is not responding. Retry later; nothing was charged |
What we need from the marketplace
- Create the FatooraConnect account and a test API key
- Add a seller onboarding screen that collects the seller's tax details and the ZATCA OTP
- Store the returned
device_idon each seller record - At checkout, split the order by seller and send one invoice request per seller
- Store
status,uuid,hashandqrfor each invoice and print the QR on the buyer's invoice - Test the full flow in sandbox (no OTP), then simulation (real OTP from ZATCA's test portal)
- Create a live API key, top up the wallet, and register each seller in production with a production OTP
The full API reference with request and response samples is in the portal under API docs.
Send your first invoice to the sandbox today.
Create an account, register a test device and watch ZATCA's response come back. Move to production when you are ready.
