Integrating Pakistani Businesses with the FBR Digital Invoicing API

If you build or maintain software for Pakistani businesses, FBR Digital Invoicing integration is now in your backlog whether you wanted it or not. Under SRO 709(I)/2025, every sales-tax-registered person in Pakistan must transmit invoices to FBR in real time via the Digital Invoicing API operated by PRAL (Pakistan Revenue Automation).

This post is the practical developer walkthrough I wish existed when I first built integrations against this API. We'll cover the architecture, the auth flow, the JSON payload, sandbox testing for the 28 mandatory scenarios, retry logic for FBR's outages, and the going-to-production checklist.

The architecture in 30 seconds

Your app → PRAL Digital Invoicing API → FBR core system
              ↓
        IRN + QR code returned to you
              ↓
        Print on the customer's invoice

Three endpoints matter:

• validateinvoicedata — pre-flight check before live submission
• postinvoicedata — actual invoice submission, returns IRN + QR code
• cancelinvoicedata — cancellation within the 72-hour correction window (post April 2026)

You authenticate with a bearer token issued via the FBR IRIS portal per registered NTN.

Step 1: Get your bearer token

1. Log in to iris.fbr.gov.pk with the business's CNIC/NTN
2. Navigate to Digital Invoicing → Integration Mode
3. Select "Proceed with PRAL as Licensed Integrator"
4. The portal generates a bearer token tied to that NTN

The token is opaque and long-lived (it doesn't expire frequently). Store it encrypted — under no circumstances commit it to source control or log it in plain text. AES-256 at rest is the minimum standard.

Step 2: Construct the invoice payload

FBR expects a strict JSON structure. Here's a minimal but complete payload for a B2B taxable supply:

{
  "invoiceType": "Sale Invoice",
  "invoiceDate": "2026-05-16",
  "sellerNTNCNIC": "1234567",
  "sellerBusinessName": "Acme Trading (Pvt) Ltd",
  "sellerProvince": "Punjab",
  "sellerAddress": "Plot 12, Lahore",
  "buyerNTNCNIC": "7654321",
  "buyerBusinessName": "Beta Industries (Pvt) Ltd",
  "buyerProvince": "Sindh",
  "buyerAddress": "Industrial Area, Karachi",
  "buyerRegistrationType": "Registered",
  "invoiceRefNo": "ACM-2026-0001",
  "items": [
    {
      "hsCode": "1234.5678",
      "productDescription": "Industrial pump model X-200",
      "rate": "18%",
      "uoM": "Numbers, pieces, units",
      "quantity": 5,
      "totalValues": 50000,
      "valueSalesExcludingST": 42372.88,
      "fixedNotifiedValueOrRetailPrice": 0,
      "salesTaxApplicable": 7627.12,
      "salesTaxWithheldAtSource": 0,
      "extraTax": 0,
      "furtherTax": 0,
      "sroScheduleNo": "",
      "fedPayable": 0,
      "discount": 0,
      "saleType": "Goods at Standard Rate (default)",
      "sroItemSerialNo": ""
    }
  ]
}

Critical fields to get right:

• sellerNTNCNIC and buyerNTNCNIC — exactly as registered with FBR; mismatches return validation errors
• hsCode — must match the actual product category (FBR validates against their HS Code database)
• rate — string format with % sign, not a number
• saleType — one of FBR's predefined values (e.g., "Goods at Standard Rate (default)", "3rd Schedule Goods", "Steel Melting and Re-Rolling")
• valueSalesExcludingST and salesTaxApplicable — must mathematically reconcile to totalValues

If your software can't render these from your existing invoice data model, you have an integration bug, not an FBR problem.

Step 3: Submit the invoice

curl -X POST 'https://gw.fbr.gov.pk/di_data/v1/di/postinvoicedata' \
  -H 'Authorization: Bearer YOUR_PRAL_TOKEN' \
  -H 'Content-Type: application/json' \
  -d @invoice.json

Or in Python:

import requests
import os

PRAL_TOKEN = os.environ['PRAL_BEARER_TOKEN']
ENDPOINT = 'https://gw.fbr.gov.pk/di_data/v1/di/postinvoicedata'

response = requests.post(
    ENDPOINT,
    headers={
        'Authorization': f'Bearer {PRAL_TOKEN}',
        'Content-Type': 'application/json'
    },
    json=invoice_payload,
    timeout=30
)

if response.status_code == 200:
    result = response.json()
    irn = result['invoiceNumber']
    qr_code = result['QRCode']  # base64-encoded image
    # Persist IRN + QR code with your invoice record
else:
    # Handle error (see error handling section below)
    pass

Step 4: Print the IRN and QR code

The IRN and QR code must appear on the invoice you give the customer. Without them, the invoice is legally invalid — even if you have a paper copy.

Your invoice template needs:

• The IRN clearly labelled (e.g., "FBR Reference: 12345678901234")
• The QR code rendered at minimum 2cm × 2cm with sufficient contrast
• A note: "Verify this invoice at fbr.gov.pk/online-invoice-verification"

Most stack PDFs use libraries like ReportLab (Python) or PDFKit (Node) to embed the base64 QR code directly.

Step 5: Sandbox first, always

FBR provides a sandbox environment at https://gw.fbr.gov.pk/di_data/v1/di/postinvoicedata_sb for testing. You must pass all 28 mandatory test scenarios before going to production.

The 28 scenarios fall into seven categories:

1. Standard sales (5 scenarios) — basic B2B/B2C at 18%
2. Third Schedule goods (3 scenarios) — retail-price-based tax
3. Reduced-rate and zero-rated supplies (4 scenarios) — 1%/5%/10%/15% rates plus zero-rated exports
4. Exempt supplies (2 scenarios) — Sixth Schedule items
5. Further tax and withholding (4 scenarios) — 3% further tax for unregistered buyers
6. Returns, debit and credit notes (4 scenarios) — linkage to original IRN
7. Special cases (6 scenarios) — multi-currency, FED on services, advance payments, exports

Most integration failures happen on scenarios 3 (reduced rates) and 6 (returns linkage). Build automated tests for these first.

Step 6: Error handling and retry logic

FBR's API isn't always up. You need queue-and-retry logic in production.

A reasonable pattern:

class FBRSubmissionService:
    MAX_RETRIES = 5
    RETRY_DELAYS = [1, 5, 30, 120, 600]  # seconds, exponential

    def submit_invoice(self, invoice_id):
        invoice = Invoice.objects.get(id=invoice_id)
        payload = self.build_payload(invoice)

        for attempt, delay in enumerate(self.RETRY_DELAYS):
            try:
                resp = requests.post(
                    self.endpoint,
                    headers={'Authorization': f'Bearer {self.token}'},
                    json=payload,
                    timeout=30
                )

                if resp.status_code == 200:
                    result = resp.json()
                    invoice.irn = result['invoiceNumber']
                    invoice.qr_code = result['QRCode']
                    invoice.status = 'submitted'
                    invoice.save()
                    return True

                if resp.status_code == 400:
                    # Validation error — log + don't retry
                    invoice.status = 'validation_error'
                    invoice.error_details = resp.json()
                    invoice.save()
                    return False

                if resp.status_code in (500, 502, 503, 504):
                    # Transient error — retry
                    time.sleep(delay)
                    continue

            except requests.Timeout:
                time.sleep(delay)
                continue

        # Exhausted retries — flag for manual review
        invoice.status = 'requires_manual_review'
        invoice.save()
        return False

Critical patterns:

• Idempotency — your invoiceRefNo should be unique per submission so FBR won't double-process
• Persistent queue — if your app crashes, pending submissions should resume on restart (use a database-backed queue, not in-memory)
• Audit log — every submission attempt, response, retry should be logged with timestamps for compliance review
• Alerting — set up alerts when invoices spend more than 1 hour in 'pending' state

Step 7: The 72-hour correction window

Under the April 2026 Sales Tax General Order No. 01 of 2026, invoices can be cancelled, deleted, or edited within 72 hours of issuance without Commissioner approval. After 72 hours, you need prior approval — slow.

Your software needs:

• A timestamp-driven "editable" flag on every invoice
• A correction endpoint that resubmits with reference to the original IRN
• A clear UI hint that says "X hours remaining to edit without approval"

Don't let users edit invoices after 72 hours via your normal flow — force them through the Commissioner-approval path.

Step 8: Production deployment checklist

Before flipping the production switch:

• [ ] All 28 sandbox scenarios passed
• [ ] Bearer token stored encrypted (AES-256 at rest)
• [ ] Token not logged in plain text anywhere
• [ ] Idempotent invoiceRefNo generation
• [ ] Queue-and-retry with exponential backoff
• [ ] Persistent queue (survives app restart)
• [ ] Audit log of every API call
• [ ] Alerting on stuck invoices (>1 hour pending)
• [ ] Monitoring of API response time (95th percentile)
• [ ] Daily reconciliation: invoice counts you sent vs counts in FBR's portal
• [ ] Backup plan for FBR downtime (when systems will queue locally and replay)
• [ ] Per-business sandbox/production toggle if you serve multiple clients
• [ ] QR code rendering tested on actual printed invoices (contrast, scannability)

Most integrations break in production on the reconciliation step — your audit log says you sent 1,000 invoices today, but FBR's portal shows 998. The missing two were rejected silently for some edge case. Catch these daily.

Step 9: Should you build this or use a managed platform?

Honest math:

• Building it yourself: ~80–200 hours upfront, plus 5–15 hours per month maintenance (FBR updates the API several times a year)
• Using a managed platform: Rs 1,500–8,000/month per business, zero engineering time

For a single-business integration, building yourself is defensible — you control everything, no vendor lock-in. For multi-business scenarios (tax consultants managing 10–100 clients), managed platforms always win on time-to-value.

I run Tallied, which handles this for Pakistani tax consultants. We charge Rs 1,500 per client business per month (wholesale tier) with white-label custom domains and a multi-client dashboard. For developers evaluating: we use the exact same PRAL API documented above, but consolidate multi-business token management, queue-and-retry, and the 28 sandbox scenarios into one interface.

For more context on the regulatory side of FBR Digital Invoicing — who must integrate, deadlines, penalties under Section 33, and how to choose the right software — see the full guide and the software comparison on the Tallied blog.

Closing notes for developers

The FBR Digital Invoicing API is well-designed by Pakistani government API standards — versioned, JSON-based, OAuth-token authenticated, with a real sandbox. The 28 scenarios are tedious but mostly straightforward. The biggest production gotchas are silent rejection, FBR downtime, and managing tokens across multiple registered persons if you're building multi-tenant.

Build idempotent. Log everything. Reconcile daily. Encrypt the token. Run all 28 scenarios in CI.

And if you ever ship anything in production against this API: print the IRN large enough that the chai-walla at your customer's office can read it. The compliance officer scanning your invoice with a phone camera will thank you.