Sign in Get started
Documentation

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.

Marketplace→FatooraConnect→ZATCA→FatooraConnect→Marketplace
Overview

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.

API base URLhttps://api.fatooraconnect.com/v1
Example

The 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.

Invoice 1

Seller A

iPhone 13

  • Seller A name, VAT number and address on the invoice
  • Signed with Seller A's ZATCA device certificate
Invoice 2

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.

Roles

Who does what

The marketplace holds one FatooraConnect account and one API key; each seller is one ZATCA device inside that account.

S

Seller (A, B, ...)

Taxpayer and legal issuer of the invoice

Generates a 6-digit OTP in ZATCA's Fatoora portal and gives it to the marketplace, once, at registration.

M

Marketplace

Your platform

Registers 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.

F

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.

Z

ZATCA

Tax authority

Issues 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.

The big picture

End-to-end flow

Once per seller: device registrationEvery order: one invoice per sellerSellerMarketplaceFatooraConnectZATCA1. OTP + tax details2. POST /v1/devices3. CSR + OTP, 6 test docs4. Seller certificate5. device_id for the seller6. Invoice, Seller A device_id7. XML signed as Seller A8. REPORTED or CLEARED9. Status, QR, hash, errorsSteps 6 to 9 repeat with Seller B's device_id for the iPhone 15
Each seller registers once; every order sends one invoice per seller

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.

Step 1 · once per seller

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)

  1. Create the FatooraConnect account and complete the company profile.
  2. 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.
  3. Top up the wallet before going live. Production invoices are charged per accepted invoice; sandbox and simulation are free.

Per-seller registration

  1. The seller logs in to ZATCA's Fatoora portal and generates a 6-digit OTP. It expires within an hour.
  2. The seller enters the OTP in the marketplace's seller onboarding screen, together with their tax details.
  3. The marketplace calls POST /v1/devices with the OTP and the seller's details.
  4. 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)
  5. 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.

Seller gets OTP from ZATCA portalPOST /v1/devices: OTP + seller detailsSeller detailscomplete?no422 details missingSend the missing fieldsyesCreate keys and CSR, send with OTPZATCA accepts OTP?no422 registration failedAsk the seller for a new OTPyes6 test documents, then certificatedevice_id returnedMarketplace saves it on the seller
Device registration: one OTP and one API call register a seller with ZATCA

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

FieldRequiredMeaning
nameYesYour own label for the device, for example the seller's shop name
environmentYessandbox, simulation or production
otpSimulation and production6-digit OTP from the seller's Fatoora portal. Not needed for sandbox
company_nameYesSeller's legal name, exactly as on the VAT certificate
vat_numberYes15 digits, starting and ending with 3
cr_numberYesCommercial registration number, 10 digits
streetYesStreet of the registered address
building_numberYes4 digits, from the national address
plot_numberYesAdditional number, 4 digits
districtYesDistrict
cityYesCity
postal_codeYes5 digits
industryNoBusiness 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

POST /v1/devices
{
  "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"
}
201 Created
{
  "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.

Step 2 · every order

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 1Request 2
device_idSeller A's deviceSeller B's device
numberORD-1001-AORD-1001-B
uuidNew UUIDAnother new UUID
LinesiPhone 13, 1 x SAR 2,000.00iPhone 15, 1 x SAR 3,500.00
VAT 15%SAR 300.00SAR 525.00
Total with VATSAR 2,300.00SAR 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

FieldRequiredMeaning
device_idYesThe seller's device from Step 1
numberYesInvoice number, up to 50 characters, unique in the account
uuidYesUnique ID of this invoice
typeYesinvoice, credit_note or debit_note
categoryYessimplified for a consumer buyer (B2C), standard for a business buyer (B2B)
issued_atNoIssue date and time. Defaults to now. Cannot be in the future
supply_dateNoDate of supply. Defaults to the issue date
buyerStandard onlyName, VAT or CR number, street, building number, city, postal code. Optional for simplified
lines[]Yesname, quantity, unit_price, optional discount, vat_category (S, Z, E, O), vat_rate (15, 5 or 0). Up to 200 lines
total_without_vatYesSum of the lines after discount, before VAT
total_vatYesSum of the VAT of the lines
total_with_vatYesAmount 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

POST /v1/invoices
{
  "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).

Step 3 · every invoice

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.

  1. Checks the API key, the rate limit and that the device_id belongs to the account.
  2. Validates every field and recalculates the totals.
  3. 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.
  4. 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.
  5. Builds the UBL 2.1 XML with that seller's name, VAT number and address from the device.
  6. Signs the XML with the seller's private key and certificate, and generates the QR code.
  7. 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
  8. Stores the result. If ZATCA accepts, the charge stays. If ZATCA rejects or cannot be reached, the charge is refunded automatically.
Buyer pays, order split by sellerPOST /v1/invoices, seller's device_idData valid,totals match?no422 validation errorNothing is sent to ZATCAyesReserve number, charge walletSign as the seller, send to ZATCAZATCA accepts?noREJECTED, charge refundedFix the data and send againyesREPORTED or CLEAREDQR, hash and UUID go to the marketplace
Invoice: each seller's invoice is checked, signed and answered in one call

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.

Step 4 · every invoice

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.

statusHTTPMeaningMarketplace action
REPORTED200ZATCA accepted a simplified invoiceSave uuid, hash, qr; show the invoice to the buyer
CLEARED200ZATCA cleared a standard invoiceSame, and download the cleared XML
REJECTED422ZATCA refused the invoiceRead error and zatca.errors, fix the data, send again
FAILED503ZATCA could not be reached or signing failedNothing was charged. Retry the same number later

Example: response for Seller A's invoice

200 OK
{
  "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 qr value as a QR code on the buyer's invoice for that seller. The buyer ends up with two invoices and two QR codes.
  • Keep uuid and number. 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.warnings can be filled even on an accepted invoice. Log them; they do not block the invoice.
  • duplicate: true means this number was already accepted earlier and the stored result was returned without a new submission or charge.
Step 5 · returns and refunds

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.

Buyer returns the iPhone 15Marketplace finds invoice ORD-1001-BPOST /v1/credit-notes, Seller B deviceOriginal accepted,UUID matches?no422 error returnedNothing is sent to ZATCAyesSign as Seller B, send to ZATCAZATCA accepts?noREJECTED, charge refundedFix the data and send againyesCredit note REPORTED or CLEAREDSeller A's invoice is not touched
Credit note: a return becomes a credit note against that one seller only

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.

FieldRequiredMeaning
device_idYesThe device of the seller who issued the original invoice
numberYesA new number for the credit note. It cannot be the original invoice number
uuidYesA new UUID for the credit note. It cannot be the original invoice UUID
invoice_noYesNumber of the original invoice being corrected
invoice_uuidYesUUID of the original invoice, as returned in Step 4
reasonYesWhy the note is issued, for example Goods returned. ZATCA requires it
categoryYesSame category as the original invoice: simplified or standard
lines[] and totalsYesOnly what is being credited, as positive amounts

Example: buyer returns the iPhone 15

POST /v1/credit-notes
{
  "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
}
200 OK
{
  "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_uuid must match the UUID held for invoice_no (reference_mismatch).
  • invoice_no must 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

CaseWhat the marketplace sends
Full return of one seller's itemOne credit note for that seller with the full line and totals
Partial refund or price reductionOne credit note for that seller with only the refunded quantity or amount
Whole order cancelledTwo credit notes, one per seller, each against its own invoice
Extra charge after the invoiceA 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.

When something goes wrong

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

codeHTTPWhat to do
unauthorized401The API key is missing, wrong or revoked
insufficient_balance402Top up the wallet, then send the invoice again
company_suspended403Contact FatooraConnect support
device_not_found404Wrong device_id, or a test key used with a production device
invoice_in_progress409The same number is being submitted now. Wait, then fetch it with GET
uuid_already_used409This uuid belongs to another invoice number. Create a new UUID
seller_details_missing422Send the missing seller details when registering the device
zatca_onboarding_failed422ZATCA refused the registration, usually a wrong or expired OTP. Ask the seller for a new OTP
device_disabled422The seller's device was disabled in the portal
(validation)422A field is missing or invalid. The body lists the problem per field
device_busy / rate_limited429Wait a few seconds (Retry-After), then retry
zatca_unreachable503ZATCA is not responding. Retry later; nothing was charged
Getting started

What we need from the marketplace

  1. Create the FatooraConnect account and a test API key
  2. Add a seller onboarding screen that collects the seller's tax details and the ZATCA OTP
  3. Store the returned device_id on each seller record
  4. At checkout, split the order by seller and send one invoice request per seller
  5. Store status, uuid, hash and qr for each invoice and print the QR on the buyer's invoice
  6. Test the full flow in sandbox (no OTP), then simulation (real OTP from ZATCA's test portal)
  7. 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.