How to Integrate Digital Invoicing and Pass All 28 Scenarios on FBR IRIS Portal

To go live with FBR digital invoicing in Pakistan, your system must pass scenario testing on the FBR IRIS portal. FBR has defined a set of test scenarios (often up to 28—numbered like SN001 to SN028) that cover different invoice types and tax situations. This guide explains, in simple steps, how to integrate digital invoicing and pass all 28 scenarios so you can get your production token and start sending real invoices.

What Is the FBR IRIS Portal and Why Are the 28 Scenarios Important?

The FBR IRIS portal is the official place where businesses and their software providers register for digital invoicing, get API tokens, and run tests. The 28 scenarios are predefined test cases that cover:

• Different invoice types (e.g. sale invoice, debit note, credit note).
• Different tax treatments (e.g. standard rate, zero-rated, exempt).
• Different buyer types (e.g. registered with NTN, unregistered, export).
• Different product or service situations so FBR can confirm your system sends correct data in all cases.

You must pass all scenarios assigned to your business (which can be 9 to 28 depending on your business nature and sector) before FBR allows you to use the production environment. So passing all 28 (or all assigned) scenarios is a mandatory step.

What You Will Need Before Starting

• FBR registration: Your business must be registered with FBR (NTN, STRN if applicable).
• Licensed integrator: FBR typically requires you to register through a licensed integrator (e.g. PRAL—Pakistan Revenue Automation Limited). They will help with portal access and technical setup.
• Static IP address: The server that will call the FBR API must have a fixed (static) IP. This IP must be whitelisted by FBR/PRAL.
• Sandbox API token and URL: From the IRIS portal, in the Sandbox Environment section. You use these only for testing, not for real invoices.
• Technical documentation: FBR’s official Technical Specification for Digital Invoicing. It describes the API, request/response format, and the 28 scenarios in detail.

Product SROs and HS Codes: Where to Get Them (Important)

For each invoice line item, FBR usually requires correct product classification. This is done using HS Codes (Harmonized System codes) and sometimes product-related SROs (statutory regulatory orders). FBR provides official lists that your system must use so that invoices are not rejected.

Product SROs and HS Codes are available in the official documentation of FBR digital invoicing. You can fetch this data from FBR’s API: it is a GET request that returns the list of HS codes (and related product/SRO information). You can use your sandbox FBR token to get all HS codes data in the sandbox environment. The exact endpoint and response format are given in the FBR technical specification (e.g. in the section for master data or reference data). Use that GET request to populate your product database with valid HS codes and stay aligned with FBR’s list instead of maintaining your own list manually.

Step 1: Register on FBR IRIS and Get Sandbox Access

1. Through your licensed integrator (e.g. PRAL), complete registration on the FBR IRIS portal for digital invoicing.
2. Log in to the IRIS portal and go to the Sandbox Environment (or similar) section.
3. Note down or generate:
   • Sandbox API base URL (e.g. the base path for all sandbox API calls).
   • Sandbox Security Token (or “API for Sandbox Token”). This is the token you will send in the request header (e.g. Authorization: Bearer <token>) for every sandbox request.
4. Use the same sandbox token to call the GET API (as per FBR documentation) to fetch HS codes and any product/SRO reference data. Store this in your system so every invoice line uses a valid HS code.

Step 2: Whitelist Your Server IP

FBR/PRAL only allows requests from approved IP addresses. Get the static IP of the server that will call the FBR API and submit it for whitelisting through the IRIS portal or your integrator. Do not run scenario tests until the IP is whitelisted, or the requests may be blocked.

Step 3: Understand the 28 Scenarios (SN001–SN028)

The technical specification document lists each scenario (e.g. SN001, SN002, … SN028) with:

• Scenario name or description (e.g. “Local sale – standard rate”, “Export – zero rated”, “Debit note”).
• Invoice type (sale, debit note, etc.).
• Tax type and rate (e.g. 18% standard, 0% zero-rated, exempt).
• Buyer details (registered/unregistered, NTN, etc.).
• Sample or required structure of the JSON request body.

Read each scenario one by one and prepare a sample JSON payload that matches the requirement. Use valid HS codes from the GET API (see above) for line items. Each test submission must use a unique invoice reference number and the current date (as per FBR rules) to avoid duplication errors.

Step 4: Build Your Integration So It Can Send Any Scenario

Your digital invoicing system (or a test tool) should be able to:

1. Build a request body in the exact JSON format FBR expects (as per the technical spec).
2. Include all mandatory fields: seller info, buyer info, invoice number, date, line items with product description, quantity, price, tax rate, tax amount, HS code per item, etc.
3. Use the sandbox token in the Authorization header for every request.
4. Send a POST request to the correct sandbox endpoint (e.g. submit invoice or submit IRN request—as per the doc).
5. Read the response and check for success or error codes. FBR returns specific codes for success and for validation failures.

For each of the 28 scenarios, you will change the payload (invoice type, tax rate, buyer type, etc.) but the way you call the API (URL, header, method) stays the same.

Step 5: Run Each Scenario One by One on IRIS

In the IRIS portal, there is usually a section where you can “run” or “submit” scenario tests. The number of scenarios assigned to you (9 to 28) depends on your business nature and sector.

1. Start with the first scenario (e.g. SN001). Build the exact JSON as required for that scenario. Use a unique invoice number and current date.
2. Send the request from your system to the sandbox API. Alternatively, some integrators allow you to paste JSON in the portal—follow the portal instructions.
3. Check the response: if FBR returns success, that scenario is passed. If they return an error, read the error message (e.g. missing field, wrong HS code, invalid buyer NTN format) and fix your payload.
4. Repeat for every scenario (SN002, SN003, … up to SN028 or until all your assigned scenarios are done). Do not reuse the same invoice number or duplicate previous submissions.

Step 6: Fix Common Failures

Typical reasons a scenario fails:

• Wrong or missing HS code: Use only codes returned by the FBR GET API (using your sandbox token). Do not invent codes.
• Duplicate invoice number or date: Use a new invoice number and current date for each test.
• Wrong tax rate or tax amount: Match the scenario (e.g. 18%, 0%, exempt) and ensure calculations are correct.
• Missing mandatory field: Cross-check the technical spec and ensure every required field is present and in the correct format (e.g. date format, NTN format).
• IP not whitelisted: Confirm your server IP is approved before testing.

Step 7: Pass All Assigned Scenarios and Apply for Production

Once all your assigned scenarios (up to 28) show as passed in the IRIS portal:

1. Complete any other portal steps (e.g. declaration, software/ERP details as required by FBR).
2. Apply for or request the production token (and production API URL). FBR will review and, after approval, issue production credentials.
3. Switch your integration to use the production URL and production token. Ensure your production server IP is also whitelisted.
4. Start sending real invoices. Keep using valid HS codes (production environment may have a similar GET API for reference data—check the latest FBR documentation).

Summary

To integrate digital invoicing and pass all 28 scenarios on the FBR IRIS portal: (1) Register and get sandbox token and URL; (2) Whitelist your server IP; (3) Fetch product SROs and HS codes from FBR’s official digital invoicing documentation using the GET request and your sandbox token; (4) Build your integration to send correctly formatted JSON for each scenario type; (5) Run each of the 28 (or all assigned) scenarios in sandbox with unique invoice numbers and current dates; (6) Fix any errors (HS code, tax, mandatory fields); (7) After all scenarios pass, get the production token and go live. Using FBR’s official documentation and their GET API for HS codes keeps your data correct and your testing smooth.

What readers say

Need Help with FBR Digital Invoicing and Scenario Testing?

Vareon can help you understand the 28 scenarios, prepare the correct payloads, and integrate with the FBR IRIS sandbox and production API. We can also guide you on using the FBR GET API for HS codes and product data. Contact us for a consultation so you can pass all scenarios and go live with confidence.