Jordan e-invoicing: the JoFotara integration guide

Jordan's national e-invoicing platform looks, from a distance, like Saudi Arabia's — a government system your billing software talks to on every sale. Up close the two are built on opposite assumptions. ZATCA holds a standard invoice back until it clears; JoFotara does not hold anything back at all.

A reporting platform, not a clearance gateway

JoFotara (الفوترة الوطنية), run by Jordan's Income and Sales Tax Department (ISTD), is a reporting model. You issue the invoice — it is valid the moment you hand it to the customer — and your system posts it to JoFotara afterward. There is no step where the platform has to approve a document before it exists.

If you have read our note on ZATCA Phase 2, this is the same distinction that separates a standard invoice from a simplified one in Saudi Arabia — except in Jordan every invoice works the reporting way. There is no Jordanian equivalent of pre-issuance clearance.

The invoice type code: three digits, three questions

Every JoFotara document carries a three-digit invoice type code, and it is the field most integrations get wrong first — because it looks like one number and is actually three independent answers concatenated.

A domestic credit sale by a sales-tax-registered business is therefore 022 — local, receivable, sales tax. Hardcoding the third digit because most invoices happen to be domestic, or swapping the digit order, files an export or a free-zone supply as something the ISTD reads as ordinary local revenue. The code has to be computed from the transaction, not written once and reused.

What the document has to carry

• A UBL 2.1 XML document — JoFotara's own profile, sent to the platform's intake endpoint as a Base64-encoded field inside a JSON body, not as a raw file upload.
• The seller's tax identification number (TIN): 8 to 12 digits, never a repeated-digit placeholder like "00000000".
• An Invoice Counter Value (ICV) — a gap-free count of every document the seller has reported, separate from the human-readable invoice number.
• A tax category per line drawn from JoFotara's own three codes — S for a taxable rate above zero, O for zero-rated, Z for exempt.
• On a credit note, a billing reference back to the original invoice's number and UUID, plus a stated reason. An unreferenced note is refused outright.

Onboarding: no certificate, just credentials

This is where the Jordanian integration is genuinely simpler than Saudi Arabia's. There is no key pair to generate, no certificate signing request, no cryptographic stamp on the document.

1. 1Enrol the business on the JoFotara portal (jofotara.gov.jo) and receive a Client-Id and a Secret-Key — the only two credentials the intake endpoint checks.
2. 2Where the seller's registration requires it, record the income source sequence number issued at enrolment — it identifies which registered activity the revenue belongs to, and is left out entirely rather than sent blank.
3. 3Test against the sandbox first, with the same Client-Id/Secret-Key shape the ISTD issues for it — sandbox credentials never touch the live register.
4. 4Send a real invoice and read what comes back before relying on it: the acceptance response carries the QR code, and that QR — not one your own system generates — is what belongs on the printed invoice.
5. 5Move to production credentials once sandbox submissions are accepted cleanly, including at least one credit note.

The integration checklist

1. 1Inventory every system that issues an invoice, the same as any e-invoicing rollout — the ERP, the till, the booking page.
2. 2Validate TINs at entry: 8 to 12 digits, and reject placeholders before they reach a real submission.
3. 3Compute the invoice type code from the transaction's actual scope, payment method and the seller's own registration — never hardcode it.
4. 4Decide who owns the ICV sequence. One counter, one system, exactly as strict as ZATCA's hash chain even though nothing here is cryptographically chained.
5. 5Store whatever QR the platform returns against the invoice record, and print that one — never a locally generated substitute.
6. 6Map credit and debit notes to carry the original invoice's number, UUID and a stated reason before your system will let one be sent.
7. 7Round JOD amounts to three decimals throughout, not two — a dinar splits into a thousand fils, and two-decimal rounding creates a real discrepancy across a full invoice run.
8. 8Retain the XML, the platform's response and the returned QR together — not just a totals report — for as long as your tax adviser says Jordanian records must be kept.
9. 9Confirm which of your registered activities are actually in scope for mandatory reporting, and from what date, directly with the ISTD — the rollout has widened over time, and a wrong assumption here is the one this checklist cannot catch for you.

Where teams actually get stuck

• Fabricating a QR code instead of printing the one JoFotara returns. A locally generated QR on a Jordanian tax invoice is unverifiable by design — it was never issued by the platform.
• Reading a JoFotara rejection as a network problem and retrying identical bytes. The platform de-duplicates on the invoice's own identifiers, so a genuine rejection needs a corrected document, not a resend.
• Treating "General Sales Tax" as a synonym for VAT in customer-facing documents. It is a multi-stage credit tax that behaves like VAT, but it is not called VAT in Jordan, and the wrong label on an invoice reads as carelessness to a buyer who knows better.
• Skipping the income source sequence number for a seller registered under more than one activity, which attributes all their revenue to an unspecified source.
• Assuming a credit note only needs the original amount. It needs the original document's number and UUID as a structured billing reference — a reason in free text alone is not enough.

How Fatouraty handles it

Fatouraty computes the invoice type code from the transaction itself — the supply's scope, how it was settled, and the seller's own registration category — rather than asking anyone to enter three digits from memory. It keeps a single gap-free ICV per workspace, builds the UBL document JoFotara's intake endpoint accepts, and stores exactly the QR the platform returns rather than generating one to print immediately.

A credit note will not transmit without a billing reference to the invoice it corrects — the original's number and UUID, plus a reason — because an unreferenced note is not something the platform will accept anyway. And because there is no certificate to onboard, moving a Jordanian workspace from sandbox to production is a matter of swapping the Client-Id and Secret-Key in Settings, not a new round of key generation.

Where to start

Start with enrolment, not engineering. The Client-Id and Secret-Key take longer to get from the ISTD than they take to configure once they arrive, so request them the same week you begin cleaning TINs and mapping which of your revenue lines are local, export, free-zone or development-zone. By the time the credentials land, the only open question left should be whether your test invoices come back accepted.