FBR Sandbox Scenarios: PRAL Sandbox Testing for Digital Invoicing
Before a business can transmit live invoices to FBR, it must pass sandbox testing on the test environment of the Digital Invoicing API run by PRAL (Pakistan Revenue Automation (Pvt.) Ltd, FBR's IT arm). FBR defines 28 test scenarios, SN001 to SN028. This guide explains what the scenarios are, which ones apply to your business, how to run them, and how the production token is issued once they pass. For software that supports every scenario, see FBR digital invoicing software.
The sandbox is the test environment of the PRAL Digital Invoicing API. Invoices posted there are not legal tax records. It is where you confirm that your system formats the invoice correctly, receives FBR's validation response, handles error codes and stores the FBR invoice number, all before going live.
Prerequisites: Before You Test
Step 1: Enrol on IRIS and get the sandbox token
- Log in to IRIS (https://iris.fbr.gov.pk/) and open the Digital Invoicing section
- Choose API integration and select your business nature (one or more) and your sector (one)
- Complete the technical details; once PRAL accepts the application, the sandbox environment opens
- View the sandbox environment details to see your sandbox security token
- Keep the token confidential; do not share it by email or chat
The sandbox token and the production token are separate. See how PRAL API tokens are issued.
Step 2: Configure your system for sandbox
In FinSmart:
- The FinSmart team adds your sandbox token to your business during onboarding; it is stored server-side and used only on the server
- Log in and choose Sandbox mode
- Sandbox invoices use their own invoice numbering, separate from production
- Each sandbox invoice carries a Scenario ID field (SN001 to SN028)
Step 3: Prepare test data
- Your own NTN (7 digits) as the seller; FBR's technical document gives the buyer values to use for each scenario
- Registered and unregistered buyers (NTN 7 digits or CNIC 13 digits), checked through FBR's registration service
- Products with HS codes and units of measure from FBR reference data
- Sale types and the tax rates FBR returns for them (standard rate 18%; reduced, zero and exempt rates for scheduled goods), plus SRO schedule and item serial numbers where needed
The 28 FBR Sandbox Scenarios
Each scenario is a sale type FBR wants to see handled correctly. The scenario ID goes in the invoice payload in sandbox mode only.
| Scenario | Description | Sale type |
|---|---|---|
| SN001 | Goods at standard rate to registered buyers | Goods at Standard Rate (default) |
| SN002 | Goods at standard rate to unregistered buyers | Goods at Standard Rate (default) |
| SN003 | Sale of steel (melted and re-rolled) | Steel Melting and Re-rolling |
| SN004 | Sale by ship breakers | Ship Breaking |
| SN005 | Reduced rate sale | Goods at Reduced Rate |
| SN006 | Exempt goods sale | Exempt Goods |
| SN007 | Zero-rated sale | Goods at Zero Rate |
| SN008 | Sale of Third Schedule goods | 3rd Schedule Goods |
| SN009 | Cotton spinners' purchase from cotton ginners (textile) | Cotton Ginners |
| SN010 | Telecom services | Telecommunication Services |
| SN011 | Toll manufacturing sale by the steel sector | Toll Manufacturing |
| SN012 | Sale of petroleum products | Petroleum Products |
| SN013 | Electricity supply to retailers | Electricity Supply to Retailers |
| SN014 | Sale of gas to CNG stations | Gas to CNG Stations |
| SN015 | Sale of mobile phones | Mobile Phones |
| SN016 | Processing or conversion of goods | Processing / Conversion of Goods |
| SN017 | Goods where FED is charged in sales tax mode | Goods (FED in ST Mode) |
| SN018 | Services where FED is charged in sales tax mode | Services (FED in ST Mode) |
| SN019 | Services | Services |
| SN020 | Sale of electric vehicles | Electric Vehicle |
| SN021 | Sale of cement or concrete blocks | Cement / Concrete Block |
| SN022 | Sale of potassium chlorate | Potassium Chlorate |
| SN023 | Sale of CNG | CNG Sales |
| SN024 | Goods listed in SRO 297(I)/2023 | Goods as per SRO 297(I)/2023 |
| SN025 | Drugs sold at a fixed sales tax rate (Eighth Schedule, serial 81) | Non-Adjustable Supplies |
| SN026 | Retailer sale to end consumer, standard rate | Goods at Standard Rate (default) |
| SN027 | Retailer sale to end consumer, Third Schedule goods | 3rd Schedule Goods |
| SN028 | Retailer sale to end consumer, reduced rate | Goods at Reduced Rate |
Which Scenarios Must Your Business Pass?
You do not have to pass all 28. IRIS lists the eligible scenarios for the business nature and sector you selected during enrolment, and only those must succeed. As a guide:
| Sector selected on IRIS | Scenarios typically required |
|---|---|
| All other sectors (for example a manufacturer or distributor) | SN001, SN002, SN005, SN006, SN007, SN015, SN016, SN017, SN021, SN022, SN024 |
| Steel | The common set plus SN003, SN004, SN011 |
| FMCG | The common set plus SN008 |
| Textile | The common set plus SN009 |
| Telecom | The common set plus SN010 |
| Petroleum / Electricity / Gas distribution | The common set plus SN012, SN013 or SN014 respectively |
| Services | The common set plus SN018, SN019 |
| Automobile | The common set plus SN020 |
| CNG stations | The common set plus SN023 |
| Pharmaceuticals | The common set plus SN025 |
| Wholesale / retail | The common set plus SN008, SN026, SN027, SN028 |
The exact list is shown on your IRIS sandbox dashboard (Eligible, Successful, Pending and Unsuccessful scenarios). Treat the IRIS list as the source of truth.
How to Run a Scenario
Steps to test
- Create an invoice in FinSmart in sandbox mode and set the Scenario ID
- Choose a buyer whose registration type matches the scenario (registered for SN001, unregistered for SN002 and so on)
- Add items with the HS code, unit of measure, sale type and rate the scenario calls for
- Click Validate FBR Invoice and fix any error codes
- Click Submit to FBR; FinSmart validates again, locks the invoice while it is being submitted, and stores the response
- Check the scenario status on the IRIS sandbox dashboard
Expected response
Status: Valid (status code 00)
FBR invoice number: returned in the response and stored on the invoice
QR code: generated from the FBR invoice number and printed on the PDF
IRIS dashboard: the scenario moves from Pending to Successful
What to verify
- ✓ The invoice shows the FBR invoice number
- ✓ The PDF carries the FBR logo, invoice number and QR code
- ✓ The activity log and API audit log show the request and response
- ✓ The IRIS sandbox dashboard lists the scenario as Successful
When a Scenario Fails
FBR returns numeric error codes at invoice level and at item level. A failed submission has no FBR invoice number, so you simply correct the data and submit again.
Status: Invalid (status code 01)
Example item error: 0053 "Provided registration type does not match with buyer's profile"
Where it shows: in FinSmart's validation feedback, and in the Error Details pop-up on the IRIS sandbox dashboard
Common error codes in sandbox
| Error code | Cause | Solution |
|---|---|---|
| 0002 | Buyer NTN or CNIC in the wrong format | NTN must be 7 digits, CNIC 13 digits |
| 0053 | Buyer registration type does not match the buyer's profile | Check the registration type through FBR's registration service and correct the customer record |
| 0052 / 0099 | HS code not valid for the sale type, or unit of measure not valid for the HS code | Pick the HS code and UoM from FBR reference data; see the HS code and UoM guide |
| 0077 / 0078 | SRO schedule number or item serial number missing on a reduced-rate, zero-rated or exempt item | Select the SRO schedule and item serial for the rate and date |
| 0104 | Calculated sales tax does not match the rate | Recalculate the tax from the rate FBR returns for the sale type and date |
| 0070 | Sales tax withheld sent for an unregistered buyer | Withholding applies only to registered or government (FTN) buyers |
| Timeout (101504) | No response from the sandbox endpoint | Check on IRIS whether the invoice was recorded before resubmitting; FinSmart flags the invoice and asks you to verify before "Force Resubmit" |
See FBR error codes explained and buyer verification for more.
Scenario-Specific Fields to Watch
- SN005, SN006, SN007 (reduced, exempt, zero-rated): the item needs the SRO schedule number and item serial number that justify the rate
- SN008 and SN027 (Third Schedule): tax is calculated on the retail price, so the fixed/notified value or retail price field must be filled
- SN017 and SN018 (FED in ST mode): the FED payable field is required
- SN021 (cement) and SN023 (CNG): the rate is rupees per unit, so sales tax is quantity multiplied by the rate
- SN022 (potassium chlorate): the rate combines a percentage with rupees per kilogram; the unit of measure must be KG
- SN026 to SN028: apply only to taxpayers registered as retailers
FinSmart's item form supports all of these fields: sales tax, further tax, withholding, extra tax, FED, discount, fixed/notified/retail value, SRO schedule and item serial, and rates as a percentage, rupees per unit or both.
Sandbox Testing Checklist
| Check | What to confirm | Status | Notes |
|---|---|---|---|
| 1. Eligible scenarios listed | IRIS shows the scenarios for your business nature and sector | ☐ | Correct the business nature or sector on IRIS if the list looks wrong |
| 2. Standard-rate scenarios | SN001 and SN002 return Valid with an FBR invoice number | ☐ | Baseline for every business |
| 3. Reduced, exempt and zero-rated | SN005 to SN007 pass with SRO schedule and item serial | ☐ | Most common source of 0077 / 0078 errors |
| 4. Sector scenarios | Your sector's additional scenarios pass | ☐ | For example SN025 for pharma, SN009 for textile |
| 5. Error handling | Validation feedback shows the error code and the item it belongs to | ☐ | Correct and resubmit without creating duplicates |
| 6. Timeout handling | A timed-out invoice is flagged and verified on IRIS before resubmission | ☐ | Prevents duplicate submissions |
| 7. Printed invoice | PDF shows the FBR invoice number and QR code | ☐ | Required on every live invoice |
| 8. Audit trail | Every FBR request and response is logged | ☐ | Useful for support and audits |
Common Sandbox Troubleshooting
Q: My invoice looks correct but FBR returned Invalid. What happened?
A: Read the error code and the item number in the response. The most common causes are a buyer registration type that does not match FBR's profile (0053), a unit of measure that is not allowed for the HS code (0099), and missing SRO schedule or item serial fields on reduced-rate or exempt items (0077, 0078).
Q: How many times can I test?
A: There is no fixed number. Sandbox invoices are not tax records, so you can repeat a scenario until it passes.
Q: Can I delete or edit sandbox invoices?
A: Sandbox submissions are test records and do not go into your sales tax return. In FinSmart a submitted invoice is locked in both modes; edits and cancellations of live invoices happen on IRIS within FBR's 72-hour rule.
Q: When do I move from sandbox to production?
A: When every eligible scenario on your IRIS dashboard shows Successful. At that point IRIS generates the production token. You are ready when:
- All eligible scenarios have passed
- Your customer and product data use the right identifiers, HS codes and units of measure
- Your team knows how to read validation feedback and handle timeouts
Moving from Sandbox to Production
Once you move to production, every submitted invoice is a legal tax record. It cannot be edited or deleted in FinSmart; corrections happen on IRIS within 72 hours of submission or by month end, whichever comes first.
Steps to go live
- Confirm the scenarios: check that every eligible scenario on IRIS shows Successful.
- Get the production token: IRIS generates it automatically once the eligible scenarios pass; view it under the production environment details. See PRAL API tokens.
- Add it to FinSmart: the FinSmart team stores the production token for your business, separately from the sandbox token.
- Log in to production mode: production submissions ask for confirmation before they are sent.
- Submit your first invoice: confirm FBR returns the invoice number and that the invoice appears on IRIS.
- Print and deliver: the invoice now carries the FBR invoice number and QR code.
Ready to Test?
FinSmart supports all 28 sandbox scenarios, validates every invoice before submission, and logs every FBR request and response. Sandbox testing before go-live is included, and the FinSmart team guides you through it.
Book a free demo