FBR Sandbox Scenario Testing: How to Pass Every Scenario and Go Live

Before your software can send real invoices to FBR, it has to pass sandbox scenario testing. FBR gives you a set of test scenarios based on your business, and your system must submit a valid invoice for each one. Only then can you generate your production token and go live.

For many businesses, this is where integration gets stuck. Scenarios fail with confusing errors, IRIS doesn’t always update right away, and a single wrong character in a sale type can block go-live for days.

This guide explains how scenario testing works, what each scenario covers, the mistakes that cause failures, and how to move from sandbox to production.

Key Takeaways

• Scenarios are assigned in IRIS based on the business nature and sector you select.

• You must pass every assigned scenario before you can generate a production token.

• A passed scenario returns status code “00” and “Valid,” along with an FBR invoice number.

• Most failures come from exact text values: sale type, rate, SRO references, and fields sent as 0 instead of blank.

• Fix problems in your master data and invoice logic, not just the test invoice, so they don’t return in production.

How FBR Sandbox Testing Works

FBR’s digital invoicing system has two environments:

The sandbox runs the same validation as production. If an invoice passes in sandbox, the same logic should pass live.

Step-by-Step: From IRIS Setup to Production

Step 1: Register for digital invoicing in IRIS

Log in to IRIS and open the digital invoicing (API integration) section. Enter your technical details, including your ERP or software provider, software name and version.

Step 2: Select your business nature and sector

Choose your business nature (such as manufacturer, importer, distributor or wholesaler) and your sector (such as pharmaceuticals, textiles, steel or automobiles). These choices decide which scenarios you’ll be asked to pass, so choose carefully and accurately.

Step 3: Get your sandbox token and scenario list

In the Sandbox Environment section, IRIS shows your sandbox token and the list of scenarios assigned to you. Many businesses receive somewhere around 9 to 12 or more, depending on their selections.

Step 4: Whitelist your server IP

FBR’s API typically requires your server’s static IP address to be whitelisted. If your requests fail with connection or access errors, check this first. Cloud-hosted systems need a fixed outbound IP.

Step 5: Configure your system for sandbox

Point your software to the sandbox endpoint, add your sandbox token as a Bearer token in the request header, and keep production settings separate.

Step 6: Submit an invoice for each scenario

For each assigned scenario, create an invoice that matches it exactly: the right sale type, buyer type, HS code, rate, SRO references and tax calculation. Include the scenario ID in your request where required.

Step 7: Confirm each scenario has passed

A successful response looks like this:

json

{
  "validationResponse": {
    "statusCode": "00",
    "status": "Valid",
    "error": ""
  }
}

along with an FBR invoice number. Check IRIS to confirm the scenario is marked as completed. IRIS can take time to update, so if a passed scenario still shows as pending, check again later before resubmitting.

Step 8: Generate your production token

Once every assigned scenario has passed, open the Production Environment section in IRIS and generate your production token.

Step 9: Switch to production carefully

• Replace the sandbox endpoint and token with production values.

• Issue one low-value real invoice first and confirm it’s accepted.

• Then go live across all users, branches and invoice types.

Step 10: Monitor every submission

Log every request and response, set alerts for failed invoices, and reconcile FBR-accepted invoices with your sales records every day for the first few weeks.

FBR Sandbox Scenarios: Reference List

FBR’s scenarios cover different types of sales. You’ll only be asked to pass the ones assigned to your business, but this list helps you understand what each one tests.

Important: copy sale types, rates and SRO references exactly from FBR’s technical documentation and reference APIs. Some contain unusual spacing or characters, and even small differences cause rejection. FBR may update scenarios over time, so always check the latest documentation.

Why Scenarios Fail: The Most Common Mistakes

1. Sale type text doesn’t match exactly

The sale type must match FBR’s expected value character for character, including spaces, capital letters and special characters.
Fix: copy sale types directly from FBR’s reference data, never retype them.

2. HS code doesn’t match the sale type

This produces the well-known error “HS Code does not match with provided sale type.” It’s common in sector-specific scenarios such as ship breaking or steel.
Fix: use an HS code that FBR allows for that scenario’s sale type. See our FBR error codes list for the full explanation.

3. Fields sent as 0 instead of blank

FBR treats “not applicable” differently from zero. Fields like extra tax may need to be sent as an empty value rather than 0 in some scenarios.
Fix: leave non-applicable fields blank where FBR expects it.

4. Wrong tax base for Third Schedule items

For Third Schedule scenarios (such as SN008 and SN027), tax is calculated on the printed retail price, not the sale value.
Fix: send the retail price and calculate tax on it.

5. Missing SRO references

Reduced-rate, exempt and special scenarios usually require an SRO or schedule number and an item serial number.
Fix: include both, exactly as FBR’s documentation shows for that scenario.

6. Rate in the wrong format

FBR expects rates as text descriptions, such as “18%,” not as plain numbers.
Fix: use the rate description from FBR’s reference API.

7. Totals don’t add up

If value excluding tax, sales tax, further tax and other amounts don’t add up to the total, the invoice is rejected.
Fix: calculate totals in your system line by line, using the same rounding every time.

8. Wrong buyer details

Registered-buyer scenarios need a valid buyer NTN in the correct format; unregistered-buyer scenarios need the buyer type set correctly.
Fix: use a valid test buyer and the correct registration type for each scenario.

9. Reused invoice reference numbers

Submitting the same invoice reference repeatedly can cause problems.
Fix: use a unique invoice reference for each submission, and a current invoice date in YYYY-MM-DD format.

10. Authentication and connection errors

A wrong token, missing “Bearer” prefix or an IP that isn’t whitelisted stops requests before they’re validated.
Fix: check the token, header format and IP whitelisting.

For a full list of error messages and fixes, see our FBR error codes list and common FBR integration errors.

Passing Sandbox Isn’t the Finish Line

Many businesses pass sandbox testing by hand-crafting test invoices, then hit errors as soon as real invoices start flowing. That’s because sandbox tests the scenario, while production tests your real data.

Before going live, make sure:

• Every sellable item has the right HS code, unit and sale type

• Every customer has a valid NTN or CNIC and correct registration type

• Every address has a province, not just a city

• Tax templates apply the right rates and SROs automatically

• Your invoice numbering uses only letters, numbers and hyphens

• Internal transfers and branch movements are excluded from FBR submission

• Failed invoices are logged and retried, not lost

• The FBR invoice number is saved against every invoice, for credit notes later

If your master data is clean, production errors are rare. If it isn’t, you’ll spend weeks fixing rejections one invoice at a time.

How ERPNext Handles Sandbox Testing and Go-Live

With an FBR integration app on ERPNext, sandbox testing becomes part of a proper setup rather than a separate exercise:

Our ERPNext FBR digital invoicing setup guide walks through the full configuration.

Sandbox Testing Checklist

• IRIS registration completed with correct business nature and sector

• Sandbox token and scenario list noted

• Server IP whitelisted

• Sandbox endpoint and token configured

• Sale types, rates and SROs copied exactly from FBR’s documentation

• Blank fields left blank, not zero

• Third Schedule items using retail price

• Totals calculated line by line

• Unique invoice references and correct date format

• Every assigned scenario returns “00” and “Valid”

• IRIS shows all scenarios completed

• Production token generated

• One low-value live invoice tested first

• Monitoring and daily reconciliation in place

Frequently Asked Questions

What is FBR sandbox scenario testing?

It’s the testing stage of FBR digital invoicing, where your software must submit valid test invoices for each scenario assigned to your business before you can receive a production token and go live.

How are FBR scenarios assigned?

Scenarios are assigned in IRIS based on the business nature and sector you select during digital invoicing registration. Different businesses receive different scenarios.

How many scenarios do I need to pass?

You must pass every scenario assigned to your business. The number varies, and many businesses receive around 9 to 12 or more.

How do I know a scenario has passed?

FBR returns status code “00” with status “Valid” and an FBR invoice number. IRIS should then show the scenario as completed, although it can take some time to update.

Why does my scenario keep failing?

The most common causes are a sale type that doesn’t match FBR’s text exactly, an HS code that doesn’t fit the sale type, fields sent as 0 instead of blank, missing SRO references, wrong tax base for Third Schedule items, or totals that don’t add up.

When do I get my production token?

After all assigned scenarios have passed, you can generate your production token from the Production Environment section in IRIS.

Do sandbox invoices count as real invoices?

No. Sandbox invoices are only for testing and aren’t filed with FBR.

Can I pass sandbox testing and still get errors in production?

Yes. Sandbox tests the scenario, but production uses your real items and customers. Clean master data is what prevents errors after go-live.

Stuck in Sandbox Testing? Bizloom ERP Can Help

Bizloom ERP helps businesses across Pakistan complete FBR sandbox testing and go live with confidence, on ERPNext and other systems. We can:

• Set up IRIS digital invoicing details and scenario testing

• Diagnose and fix failing scenarios

• Map HS codes, units, sale types, rates and SROs for your items

• Clean customer NTN, registration type and province data

• Configure sandbox and production settings, logging and retries

• Monitor submissions after go-live

Learn more about our FBR integration services, see what FBR integration actually costs, or check which businesses must integrate with FBR. For the full picture, read our complete FBR integration guide. Retailers with POS systems should also see FBR POS integration for retailers.

Stuck on a scenario right now? Book a Free ERP Assessment with Bizloom ERP and our team will help you find what’s failing and get you to production.