All Pakistan (federal)Sales tax on goods⚡ Sandbox + Production

FBR API Integration

Submit invoices to the Federal Board of Revenue through one canonical TaxBridge API. Sandbox, production, authentication, error handling and logs — without studying the FBR API directly.

Start FBR Sandbox View Documentation

FBR covers sales tax on goods in All Pakistan (federal).

POST /api/v1/invoices

curl -X POST https://taxbridge.themetasum.com/api/v1/invoices \
  -H "Authorization: Bearer tbk_test_9f3a21c7b4d6e8f0_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b6d1c4e-7f9a-4a51-8d3c-2e5f7a91b204" \
  -H "X-Tax-Authority: PRA" \
  -d '{
    "invoiceNumber": "INV-10001",
    "invoiceDate": "2026-08-10T10:30:00",
    "invoiceType": "Sale",
    "currency": "PKR",
    "paymentMode": "Cash",
    "customer": { "name": "Walk-in Customer" },
    "items": [{
      "description": "Chicken Karahi Full", "hsCode": "11001010",
      "quantity": 1, "unitPrice": 1500.00,
      "taxRate": 16, "taxAmount": 240.00, "total": 1740.00
    }],
    "subTotal": 1500.00, "tax": 240.00, "total": 1740.00
  }'

FBR in one call

Integrate FBR Without the FBR-Specific Work

You send TaxBridge one canonical invoice. TaxBridge applies FBR’s field names, casing, money identity and success rules, then returns a single normalized result.

Authority	Federal Board of Revenue
Jurisdiction	All Pakistan (federal)
Covers	Sales tax on goods
Header	`X-Tax-Authority: FBR`
Registration	iris.fbr.gov.pk

POST /api/v1/invoices

curl -X POST https://taxbridge.themetasum.com/api/v1/invoices \
  -H "Authorization: Bearer tbk_test_9f3a21c7b4d6e8f0_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b6d1c4e-7f9a-4a51-8d3c-2e5f7a91b204" \
  -H "X-Tax-Authority: FBR" \
  -d '{
    "invoiceNumber": "INV-10001",
    "invoiceDate": "2026-08-10T10:30:00",
    "invoiceType": "Sale",
    "currency": "PKR",
    "paymentMode": "Cash",
    "customer": { "name": "Walk-in Customer" },
    "items": [{
      "description": "Chicken Karahi Full", "hsCode": "11001010",
      "quantity": 1, "unitPrice": 1500.00,
      "taxRate": 16, "taxAmount": 240.00, "total": 1740.00
    }],
    "subTotal": 1500.00, "tax": 240.00, "total": 1740.00
  }'

How FBR Integration Works

Four steps from account to your first approved FBR invoice.

1. Register & get approved

Create your TaxBridge company and verify your email. An admin approves the company for production access.

2. Subscribe & store FBR credentials

Pick a plan for FBR and fill the credential form. For FBR: A numeric POS ID plus a production security token (Bearer). FBR issues the sandbox token per registered integrator, so it is pasted into TaxBridge once and reused for every sandbox submission.

3. Create an API key

Generate a test or live key, optionally pinned to FBR. The full key is shown once and stored only as a hash.

4. Post an invoice

Send your canonical invoice with X-Tax-Authority: FBR. Print the returned qrCode and keep the submissionId.

FBR authority quirk TaxBridge handles for you

Success means HTTP 2xx and a body code of 100. Sandbox falls back to the shared test POS ID 965995 when a company has none; production must use the company’s own numeric POS ID.

🔑

Credentials, encrypted

Your FBR credentials are AES-256-GCM encrypted at rest and never returned to your app.

🧪

Sandbox & simulator

Test FBR end-to-end before you hold production credentials.

⚠

Normalized errors

FBR rejections come back as a single status with a readable authorityMessage.

📋

Full request logs

Every FBR submission is logged with request, response and status for debugging.

🏢

Multi-branch

Run many outlets under one company — each branch’s FBR submissions are tracked separately.

🔄

Idempotent retries

A repeated Idempotency-Key replays the stored FBR result with no double submission.

FBR responses your code handles

HTTP	Meaning	What your code does
`201`	Approved by the authority	Print `qrCode`, store `submissionId`
`200`	Idempotent replay (`duplicate:true`)	Treat like the original — no quota consumed
`400 INVALID_INVOICE`	Normalizer rejected it; `details[]` lists every problem	Fix and resubmit — no quota consumed
`402 QUOTA_EXCEEDED`	Plan limit hit or subscription expired	Upgrade or renew
`409 DUPLICATE_INVOICE`	Invoice number already approved for this authority + environment	Do not resubmit
`422`	Authority rejected it (`status:"REJECTED"`)	Read `authorityMessage`, fix the data
`429`	Rate limit or sandbox soft cap	Honour `Retry-After`
`502 / 504`	Authority errored or timed out	Retry with the same `Idempotency-Key`

FBR API — FAQ

What is FBR API integration?

FBR API integration connects your software to the Federal Board of Revenue system for sales tax on goods, submitting each invoice and returning the FBR invoice number and QR value. TaxBridge exposes one canonical invoice API and translates it to FBR’s format and success rules.

What software needs FBR integration?

Retailers, wholesalers, manufacturers, importers and any software selling taxable goods in Pakistan — POS systems, ERPs, e-commerce and accounting software.

How does FBR decide success?

FBR treats a submission as approved only when the HTTP response is 2xx and the response body code is 100. TaxBridge normalizes that into a single APPROVED status and a standard error when it is not.

What POS ID does sandbox use?

In sandbox, FBR falls back to the shared test POS ID 965995 when a company has none. Production must use the company’s own numeric POS ID.

Also integrating another province? See PRA · SRB · KPRA or the unified tax API.