How to Integrate the FBR API with Your POS Software

Step 1 — Store your FBR credentials

FBR issues its own credential set. In TaxBridge you enter it once on the Authorities / Credentials form, which renders exactly the fields FBR needs:

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.

Credentials are AES-256-GCM encrypted at rest and never returned to your app. Don't have production credentials yet? Turn on Use simulator (sandbox) and build your whole integration first — see how to test tax APIs.

Step 2 — Create an API key

Generate a key scoped to the test environment (and optionally pinned to FBR). The full key — tbk_test_... — is shown once and stored only as a SHA-256 hash. Keep it as a secret; a lost key is regenerated, not recovered.

Step 3 — POST your first FBR invoice

Send your canonical invoice to POST /api/v1/invoices with the FBR header and an Idempotency-Key:

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
  }'

Print the returned qrCode on the receipt and store the submissionId so you can query status later.

The FBR 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.

Step 4 — Go to production

Once your sandbox flow is verified, complete company and branch configuration, store your production credentials and generate a tbk_live_ key. Sandbox and production stay completely separate — a sandbox key never files a real FBR invoice. See production onboarding.

Frequently asked questions