JoFotara integration for Jordan e-invoicing

How the integration actually works

The national system receives an invoice at the moment it is issued and approves it, returning a reference number, a UUID and a QR code. The invoice is not a PDF and not an image — it is an XML file structured to the UBL 2.1 standard. What you print for the customer is only a visual representation of that file.

The full integration flow as the official Portal user guide describes it is published on the national integration and ERP page, and the field and error reference lives in the API documentation.

Client-Id and Secret-Key

A programmatic integration runs on two keys the department issues to your establishment, sent in the headers of every request. Before any of it, the business must hold an active tax number and be registered on the electronic tax portal; the e-invoicing account is then created from inside it.

Mandatory invoice fields

If any one of these is missing the invoice is rejected — regardless of whether the amounts are correct.

Invoice type and payment method codes

This is where the most common error of all occurs. The two codes are not independent: the permitted payment method follows the document type.

UBL 2.1 and XML in practice

UBL (Universal Business Language) is an international standard for representing business documents in XML, and version 2.1 is the one the Jordanian system adopts. You will not need to memorise it, but understanding its shape helps you read error messages. An invoice is four blocks: the document header, the parties, the lines, and the totals.

<Invoice>
  <cbc:ID>INV-2026-0418</cbc:ID>
  <cbc:UUID>8f3c1e42-…</cbc:UUID>
  <cbc:IssueDate>2026-04-18</cbc:IssueDate>
  <cbc:InvoiceTypeCode name="011">388</cbc:InvoiceTypeCode>
  <cac:AccountingSupplierParty>   <!-- seller -->
  <cac:AccountingCustomerParty>   <!-- buyer -->
  <cac:SellerSupplierParty>       <!-- income source sequence -->
  <cac:InvoiceLine>               <!-- one line per item -->
  <cac:LegalMonetaryTotal>        <!-- totals -->
</Invoice>

Tax is calculated per line, not per invoice

The general sales tax rate in Jordan is 16%, with reduced rates and goods or services that are exempt or zero-rated depending on their nature.

taxable base = (quantity × unit price) − discount
tax          = taxable base × (rate ÷ 100)
line total   = taxable base + tax

// example: 2 × 120 with a discount of 20 and 16% tax
// base = 220, tax = 35.200, total = 255.200

Zero-rated and exempt lines are sent under a different tax category (Z rather than S) together with the exemption reason. Taxable and exempt lines can appear on the same invoice, and the totals must reflect that precisely.

Why invoices are rejected

Four of these five are caught by pre-validation and never reach the department. The full error table with the department's codes and their translations is published in the national e-invoicing guide.

The QR code and invoice verification

After acceptance the system returns a QR code that you place on the printed copy or the PDF, and anyone can scan it to confirm the invoice is genuinely registered and its amounts unaltered. In practice that means two things: do not print the invoice before the acceptance response arrives, because the code does not exist before it; and keep the code with the invoice record, because it is part of your document rather than decoration on it.

Systems we connect

Proven integration patterns. And if your system is not on the list, the endpoint itself is enough.

The product names above are trademarks of their respective owners, mentioned only to indicate technical compatibility.

Frequently asked questions

How do I connect my accounting system to Jordan's national e-invoicing system (JoFotara) over the API?

A programmatic integration needs three things: a taxpayer account on the national portal, a pair of integration keys (Client-Id and Secret-Key) issued by the Admin account from the device-linking screen, and a layer that builds the invoice as UBL 2.1 XML, minifies it, and Base64-encodes it before sending. You do not need to replace your accounting system: the layer sits between your system and the tax department, and your system stays the source of truth for sales data.

Which fields are mandatory on a JoFotara invoice?

Invoice number (cbc:ID), which must be unique; the UUID; the issue date in YYYY-MM-DD form; the invoice type code together with a payment method that matches it; the seller tax number; the income source sequence; the buyer details; at least one line item with a quantity above zero; and the totals carried to three decimal places. A missing field rejects the invoice regardless of whether the amounts are correct.

What is the income source sequence and why are my invoices rejected because of it?

The income source sequence identifies the activity the invoice was issued against, and it sits in UBL inside cac:SellerSupplierParty. It is the field most often forgotten when building a first integration, and its absence is a recurring rejection cause. The fix is to add it once to the static seller data so it repeats automatically on every invoice rather than being entered by hand.

What are the invoice type and payment method codes in JoFotara?

A tax invoice is code 388, and its permitted payment methods are 011 for cash and 021 for credit. A credit note or return is code 381, and its permitted payment methods are 013 for a cash return and 023 for a credit return. The two codes are not independent: 388 never pairs with 013 or 023, and 381 never pairs with 011 or 021. Mismatching them is by far the single most common error.

Why does JoFotara reject invoices, and how do I fix it?

Five causes account for most rejections: the invoice type code conflicting with the payment method, a missing income source sequence, amounts rounded to two decimal places instead of three, XML sent without being minified, and reusing an invoice number. Four of the five can be caught by pre-validation so they never reach the tax department at all.

Why must amounts carry three decimal places?

The Jordanian dinar divides into 1,000 fils, so the system expects three decimal places — 255.200, not 255.20. Rounding to two is a recurring rejection cause for teams coming from systems built around the dollar or the euro, because the totals then fail to reconcile against the sum of the line items.

Can WooCommerce, Shopify or a point-of-sale system be connected to JoFotara?

Yes. Any system that can send an HTTPS request can be connected. Proven patterns cover Odoo, SAP, Microsoft Dynamics, WooCommerce, Shopify and point-of-sale systems, as well as custom in-house systems. On an online store the invoice is issued automatically when the order completes; on a point of sale it is sent the moment the sale closes and the QR code prints straight onto the receipt.

Where do the Client Id and Secret Key come from?

From the device-linking screen inside your account on the national portal, which is available to the main (Admin) account only — a subuser organises invoices through the interface and cannot issue integration keys. Both keys travel in the headers of every request and amount to your establishment's tax signature: whoever holds them can issue invoices against your account, so never send them by email or WhatsApp and never embed them in application or website code.

Does the invoice carry a QR code, and how does a customer verify it?

Once an invoice is accepted the system returns a reference number, a UUID and a QR code. Anyone — your customer or a tax auditor — can scan it to confirm the invoice is genuinely registered and that its amounts have not been altered. In practice this means one thing above all: do not print the invoice before the acceptance response arrives, because the code does not exist before it.

Is my business required to issue e-invoices, and from when?

The mandate in Jordan expands gradually in tranches, and the tranche your business falls into is set by the Income and Sales Tax Department based on factors such as annual turnover, the nature of the activity, and sales tax registration. Mandate dates and the penalties attached to late adoption are revised more than once, so do not rely on dates from unofficial sources: check the department's announcements or your tax adviser about your specific tranche.

How long does an integration project take?

A typical integration takes between a day and a week depending on how complex your system is. The path has four stops: a sandbox key, which takes minutes to obtain; field mapping, to establish where each required field lives inside your system; integration and testing against real cases (a standard invoice, a credit sale, one with a discount, one with exempt lines, and a credit note); then the cutover to live using your own establishment's keys.