Skip to main content

FBR Digital Invoicing | Pakistan (Rule 150Q)

This is the Pakistan country pack for the ECOSIRE GCC E-Invoicing | Core Engine. It implements FBR Digital Invoicing under Rule 150Q (Sales Tax Rules 2006, SRO 350(I)/2021) — a Continuous Transaction Control (CTC) mandate where your Odoo instance POSTs a JSON invoice payload to PRAL (Pakistan Revenue Automation Ltd) or an FBR-licensed integrator, receives an IRN (Invoice Reference Number) and QR data, stamps the invoice, and only then permits the invoice to be sent to the buyer.

This pack requires the GCC E-Invoicing | Core Engine. Install ecosire_einvoice_core first, then install this pack on top.

Compatibility: Odoo 17 / 18 / 19 (Community or Enterprise) Price: $349 (one-time) + Core Engine $499 License: Up to 3 domain activations Category: Accounting / Localizations / EDI

Sandbox / production credentials required for live transmission

The PRAL production and sandbox API base URLs, token endpoint paths, and the exact FBR JSON schema field names are gated behind PRAL portal registration and/or integrator NDAs. No production URL is hardcoded in this module. You must supply the base URL, token path, Client ID, and Client Secret from your own PRAL or integrator account. Until those are configured, the module operates in Manual Export mode — you can build and download the FBR JSON for upload to the PRAL portal without any live API access.

What it does​

  • FBR JSON invoice builder — maps account.move to the FBR JSON schema (NOT UBL/XML; FBR uses a proprietary JSON schema, distinct from ZATCA's UBL 2.1).
  • Pakistani taxpayer fields — STRN (13-digit), NTN (7-digit), and CNIC (13-digit) with regex validation on contacts (res.partner).
  • HSN / HS tariff code field on products — required for goods per the FBR schema.
  • Pakistan GST rate handling — standard 17%, reduced rates (1/3/5/8/10/12/15%), zero-rated, and exempt categories.
  • Pluggable transport adapter — ships the PRAL-direct OAuth2 client_credentials adapter. Additional FBR-licensed integrator adapters (Axacore, SAPiens, NetSol) are built as sub-modules once their API docs or sandbox credentials are obtained.
  • Submission audit log (fbr.submission) — stores the full request and response JSON for every transmission attempt with a four-state lifecycle: draft → submitted → cleared → rejected.
  • IRN + QR lifecycle on account.move — fbr_irn, fbr_state, and fbr_qr_data fields track the authority response per invoice.
  • IRN-gating — a posted customer invoice or credit note cannot be emailed to the buyer (action_invoice_sent) without a valid IRN. This enforces the regulatory hard rule.
  • Manual-export fallback — the Build FBR JSON button downloads the payload as a .json file for portal upload, so you can operate while awaiting sandbox credentials.
  • Retry cron — re-attempts rejected submissions up to 6 times with exponential backoff (15 min × 2ⁿ, capped at 24 hours).
  • Test Connection button — validates your PRAL credentials before sending any invoice.
  • License enforcement via ecosire_license_client.

Requirements​

RequirementDetail
Odoo17.0, 18.0, or 19.0 (Community or Enterprise)
Core engineecosire_einvoice_core installed and licensed
Module dependencyecosire_license_client
Python packagesrequests (standard Odoo dependency)
LicenseAn active ECOSIRE license for ecosire_einvoice_pk
PRAL / integrator accessRequired for live API transmission (sandbox or production). Not required for Manual Export mode.

Installation​

  1. Install and configure the GCC E-Invoicing | Core Engine first.
  2. Download this pack's ZIP from your ECOSIRE Dashboard and extract it to your addons directory: 
    unzip ecosire-einvoice-pk-*.zip -d /opt/odoo/addons/
    sudo systemctl restart odoo
  3. In Odoo go to Apps, click Update Apps List.
  4. Search for ECOSIRE E-Invoicing | FBR Digital Invoicing — Pakistan and click Install (Odoo installs ecosire_einvoice_core and ecosire_license_client automatically if not already present).
  5. Enter your ECOSIRE license key when prompted.

After installation, an E-Invoicing → FBR (Pakistan) submenu appears under Accounting.

Configuration​

Step 1: Activate your ECOSIRE license​

Go to Settings → ECOSIRE License and activate the license key for ecosire_einvoice_pk. The module enforces a valid active license for all live API operations. Manual Export mode is available before license activation so you can inspect the JSON output without going live.

Step 2: Open the FBR Configuration​

Navigate to Accounting → E-Invoicing → FBR (Pakistan) → Configuration. One configuration record is created per company. Fill in the following fields:

FieldDescription
IntegratorPRAL — Direct Integration for live API transmission; Manual Export for JSON-download-only mode
EnvironmentSandbox / Test while setting up; Production only after a successful sandbox round-trip
API Base URLYour PRAL sandbox or production base URL, obtained from the PRAL integration portal after registration (e.g. https://sandbox.pral.com.pk). Left blank by default — must be supplied by you.
Token Endpoint PathOAuth2 token path (default /oauth/token — confirm from PRAL docs)
Invoice Submit PathInvoice submission path (default /api/v1/invoice — confirm from PRAL docs)
Seller STRNYour company's 13-digit Sales Tax Registration Number
Client IDYour PRAL OAuth2 client identifier
Client SecretStored in Odoo system parameters (encrypted) — never written to a model field. Enter it once; the form shows a Client Secret Configured indicator
Sandbox VerifiedTick only after a successful sandbox round-trip. Production transmission is blocked until this is ticked.

Click Test Connection to verify that the token endpoint is reachable and your credentials are accepted before sending any invoice.

Step 3: Set up partners (contacts)​

Open each Pakistani partner's contact record. Under the FBR / Pakistan tab added by this pack, fill in:

  • STRN — 13-digit Sales Tax Registration Number (for B2B buyers who are sales-tax registered)
  • NTN — 7-digit National Tax Number (for B2B buyers)
  • CNIC — 13-digit Computerised National Identity Card number (for B2C / individual buyers)

Regex validation runs on save for all three fields. For B2B invoices, STRN or NTN is required on the buyer. For B2C (individual consumers), CNIC is required.

Step 4: Set HSN codes on products​

Open the relevant products and enter the HSN Code (HS tariff code) in the FBR field added on the product form. This field is required by the FBR JSON schema for goods. Services may differ — confirm with your PRAL integration guide.

Step 5: Configure GST tax rates​

Use Odoo's standard Accounting tax configuration to set up the applicable Pakistan GST rates (17%, reduced rates, zero-rated, exempt). The FBR JSON builder reads the tax_id on invoice lines to populate the taxRate and taxAmount fields in the payload.

Daily usage​

Submitting an invoice to FBR​

  1. Post the customer invoice (or credit note) in Odoo Accounting as usual.
  2. On the posted invoice, two new buttons appear in the action toolbar:
    • Submit to FBR — sends the invoice to PRAL/integrator via the live API (requires credentials configured and Sandbox Verified ticked for production).
    • Build FBR JSON — downloads the FBR JSON payload as a .json file for manual upload to the PRAL portal. Available immediately without any API configuration.
  3. After a successful Submit to FBR, the IRN and QR data are written back to the invoice:
    • FBR IRN field — the Invoice Reference Number from PRAL.
    • FBR Status — Cleared (IRN received).
  4. The invoice can now be sent to the buyer. Attempting to email an in-scope invoice without an IRN raises a UserError:

    "FBR compliance: invoice INV/2026/00001 cannot be sent to the buyer without an IRN. Submit it to FBR first (or use Build FBR JSON and obtain an IRN via the portal)."

Viewing the submission audit log​

Go to Accounting → E-Invoicing → FBR (Pakistan) → Submissions. Each fbr.submission record shows:

  • The linked invoice, state, IRN, HTTP status, and status message.
  • The raw request JSON and raw response JSON (full audit trail — FBR may inspect your integration logs).
  • Retry count and next scheduled retry time for rejected submissions.

Retry behaviour​

The FBR Retry scheduled cron runs automatically. For each rejected submission whose backoff window has elapsed, it re-attempts action_fbr_submit. Retries are capped at 6 attempts. After 6 failures the record stays in rejected state and the issue requires manual review (usually a misconfigured credential, an unreachable endpoint, or a schema validation error from PRAL).

Credit notes and debit notes​

Post a credit note (refund) in Odoo in the usual way. The FBR JSON builder sets invoiceType to CR (credit note) or DN (debit note) and includes the originalInvoiceIRN field linking back to the cleared original invoice. Submit and receive an IRN in the same way as a regular invoice.

Compliance scope​

Rule 150Q currently applies to:

  • Phase 1 — Tier-1 retailers (above the annual turnover threshold set by FBR): mandatory since 2021, with enforcement strengthened through 2025–2026.
  • Phase 2 — Manufacturers, importers, wholesalers: phased in from 2023–2024.
  • Phase 3 — Broader registered taxpayers: ongoing FBR expansion.

Both B2B and B2C invoices are in scope for Tier-1 retailers. Check the current FBR SRO amendments and the official approved-integrators list at fbr.gov.pk for the latest scope and effective dates.

Troubleshooting​

IssueSolution
"FBR sandbox configuration required: no API Base URL is set"Enter your PRAL base URL in FBR (Pakistan) → Configuration → API Base URL. PRAL provides this when you register on their integration portal.
"Client ID and/or Client Secret are not set"Enter your PRAL OAuth2 Client ID and save the Client Secret using the Set Client Secret action on the configuration form.
"Production transmission is blocked until Sandbox Verified is ticked"Complete a successful sandbox round-trip first, then tick Sandbox Verified on the FBR Configuration.
"This configuration is in Manual Export mode"Switch Integrator from Manual Export to PRAL — Direct Integration for live API transmission.
License not activeGo to Settings → ECOSIRE License and activate your license key for ecosire_einvoice_pk.
"Only posted invoices can be submitted to FBR"Confirm and post the invoice before clicking Submit to FBR. Draft invoices are not submittable.
"Invoice already has IRN"The invoice has already been cleared. Use a credit note to correct it rather than resubmitting.
Submission stays in rejected state after multiple retriesOpen the fbr.submission record and read the Response JSON field — PRAL returns a statusMessage with the rejection reason. Common causes: malformed STRN/NTN/CNIC, missing HSN code, schema version mismatch.
Test Connection failsVerify your API Base URL, Token Endpoint Path, Client ID, and Client Secret. Ensure your server can reach the PRAL endpoint (no firewall block on outbound HTTPS).
Buyer receives invoice without QR codeCheck that the IRN was received before printing — the QR data is populated by fbr_qr_data only after a cleared submission.

FAQ​

Do I need the GCC E-Invoicing Core Engine? Yes. This pack provides the Pakistan-specific JSON builder, validators, and PRAL adapter, but the submission orchestration, audit infrastructure, and license framework all live in ecosire_einvoice_core. Install the core engine first.

Can I use Manual Export mode in production? Yes — set Integrator to Manual Export, click Build FBR JSON on any posted invoice, and upload the .json file to the PRAL portal manually. This mode works without any API credentials and is suitable while awaiting PRAL sandbox access or while the live adapter is being sandbox-verified.

Is a digital signature required before submission? Based on the FBR architecture, PRAL handles signing server-side after validation — unlike ZATCA where the seller signs the XML before submission. This module does not apply a client-side signature. Confirm with your PRAL integration guide before going live.

Are private integrators (Axacore, SAPiens, NetSol) supported? The module ships with the PRAL-direct OAuth2 adapter. Additional adapters for FBR-licensed private integrators are built as sub-modules once their API documentation or sandbox access is obtained. Contact support if you need a specific integrator adapter.

Does this support Point of Sale (POS)? No. The current release covers account.move customer invoices and credit/debit notes. POS integration is not included.

Why are the PRAL endpoint paths not pre-filled? The PRAL production and sandbox REST API specifications are gated behind registration — they are not publicly accessible. Per the FBR Digital Invoicing API contract, the base URL and token endpoint path are P0 blocking-unknowns until you register on the PRAL integration portal. Hardcoding an unverified URL would risk sending real invoice data to a wrong endpoint. You must supply these from your PRAL registration.

Support​

Last updated on