How to Integrate FBR API with Your Current Cloud Based POS System

If you run a business in Pakistan and use a cloud-based Point of Sale (POS) system, you need to connect it to the Federal Board of Revenue (FBR) so that every sale is reported in real time. This guide explains, in simple steps, how to integrate the FBR API with your existing cloud POS—from registration to going live.

What You Will Need Before Starting

Before you start the integration, make sure you have the following:

• FBR registration: Your business must be registered with FBR (NTN and STRN if applicable).
• Cloud POS system: A POS that can send data over the internet (API or similar).
• Stable internet: A reliable connection so invoices can be sent to FBR without failure.
• Technical help (optional but useful): A developer or your POS vendor who can work with APIs.

Step 1: Register for FBR Digital Invoicing (POS Client Registration)

First, you must tell FBR that you will be using a POS system to send invoices. This is called POS Client Registration.

1. Go to the official FBR website: https://fbr.gov.pk.
2. Log in with your FBR credentials (business or authorized person).
3. Find the section for Registration and then POS Client Registration (or Digital Invoicing / POS registration, as shown on the portal).
4. Fill in all required details for each business location (branch) where you will use the POS. This usually includes:
   • Business name and NTN
   • Branch address and name
   • Contact person and phone number
   • Type of business and nature of sales
5. Submit the form. After verification, FBR will approve your registration and give you a POS Registration Number (or POS ID) for each branch. Keep this number safe—you will need it in the next steps.

Step 2: Get Your API Credentials (Sandbox and Production)

FBR provides two environments: Sandbox (for testing) and Production (for real invoices). You need credentials for both.

• Sandbox: Used to test your integration without affecting real tax data. You get a sandbox API URL and a sandbox token.
• Production: Used when you are ready to send real invoices. You get a production API URL and a production token.

In the FBR IRIS portal (or the portal where you did POS registration), look for sections like API for Sandbox and API for Production. Generate or copy:

• API base URL (different for sandbox and production)
• API token (or security token) for authentication

Store these in a secure place. Never share your production token publicly or in code that is visible to others.

Step 3: Whitelist Your Server IP (If Required)

FBR/PRAL often requires that only specific IP addresses can call their API. This is called IP whitelisting.

1. Get the static (fixed) IP address of the server that will send requests to FBR (e.g. your cloud POS backend server). If you use a cloud provider (AWS, Azure, etc.), note the outbound IP or use a fixed IP.
2. In the FBR/PRAL portal or through your licensed integrator, submit this IP for whitelisting.
3. Wait for confirmation that the IP has been whitelisted before testing or going live.

Step 4: Read the Official FBR Technical Documentation

FBR publishes official technical documentation for Digital Invoicing API integration. It includes:

• Exact API endpoints (URLs) for submitting invoices
• Request format (e.g. JSON structure)
• Required fields (invoice number, date, buyer NTN, items, tax, etc.)
• Response codes and error messages

You can find this on the FBR website under Technical Documentation for Digital Invoicing. Use this document as the single source of truth for field names, data types, and allowed values.

Step 5: Design How Your Cloud POS Will Talk to FBR

Your cloud POS does not talk to FBR directly from the cashier screen. Usually, the flow is:

• POS (front-end): When a sale is completed, the POS creates an invoice (invoice number, date, line items, tax, total).
• Your backend server: The POS sends this invoice data to your own cloud backend (via your API or queue).
• Your backend to FBR: Your backend then calls the FBR API with the same invoice data in the format FBR expects.

So you need a small “connector” or “integration layer” on your backend that:

1. Receives invoice data from your POS.
2. Maps it to FBR’s required JSON format (as per technical documentation).
3. Sends a POST request to the FBR API with the correct headers (e.g. Authorization: Bearer your_token).
4. Reads the response and saves the FBR response (e.g. acknowledgment or invoice ID) and handles errors (e.g. retry or alert).

Step 6: Build the Integration (High-Level Steps)

Here is a simple order of tasks for your developer or vendor:

1. Create an authentication step: Use the FBR token (sandbox first) in the request header (e.g. Authorization: Bearer <token>) so FBR accepts the request.
2. Build the request body: For each invoice, build a JSON object that includes all mandatory fields from the FBR documentation (e.g. invoice number, date, seller and buyer details, line items with product name, quantity, price, tax rate, tax amount, total).
3. Send a POST request: To the FBR endpoint (e.g. /api/invoice or as specified in the docs). Use HTTPS only.
4. Handle the response: If FBR returns success, store the reference or acknowledgment they send. If they return an error, log it and optionally retry or notify staff.
5. Link back to your POS: Save the FBR response (e.g. IRN or acknowledgment number) against the invoice in your database so you can show or print it on the receipt if required.

Step 7: Test in Sandbox First

Always test with the sandbox environment before using production.

• Use the sandbox API URL and sandbox token.
• Create test invoices from your POS (or via a test tool) and ensure they are sent to the sandbox.
• Check that FBR sandbox returns success and that your system stores the response correctly.
• Test error cases too (e.g. wrong format, missing field) and confirm your system handles them without crashing.

Step 8: Switch to Production and Go Live

When all sandbox tests pass:

1. Switch your integration to use the production API URL and production token.
2. Ensure your server IP is whitelisted for production.
3. Run a few real invoices and verify they appear on the FBR side (e.g. in the FBR portal or as advised by FBR/PRAL).
4. Train your staff so they know that every sale is now being reported to FBR and that they should not duplicate or delete invoices without proper process.

Step 9: Ongoing Compliance and Maintenance

• Keep your API token and credentials secure. Rotate tokens if FBR supports it and if there is a security concern.
• Monitor failed requests and fix them (e.g. format changes, new required fields) as FBR may update the API.
• Stay updated with FBR circulars or notices about digital invoicing so you can adapt your integration when required.

Summary

Integrating the FBR API with your cloud POS means: (1) registering as a POS client with FBR and getting POS ID, (2) getting sandbox and production API URLs and tokens, (3) whitelisting your server IP, (4) building a backend connector that converts POS invoice data into FBR’s format and POSTs it to FBR, (5) testing fully in sandbox, and (6) switching to production and monitoring. Follow the official FBR technical documentation for exact endpoints and field names, and you will have a clear, step-by-step path to a compliant integration.

What readers say

Need Help with FBR POS Integration?

Vareon can help you with FBR registration, understanding the technical documentation, and connecting your cloud POS to the FBR API. We work with businesses and their software vendors to ensure a clean, compliant integration. Contact us for a consultation tailored to your POS and business type.