Key Takeaway
Your FBR sandbox token is a 5-year Bearer authentication credential issued by the IRIS portal. It lets you test digital invoicing in a safe environment before going live, and getting one is a mandatory step under SRO 69(I)/2025 and SRO 709(I)/2025. This guide walks Pakistani business owners through every step, from logging into IRIS to running your first test invoice.
Why You Need an FBR Sandbox Token Before Going Live
Pakistan's Federal Board of Revenue requires every business that issues B2B sales tax invoices to integrate with its Digital Invoice System (DIS). Before your invoices flow into the production system that issues real 22-digit FBR invoice numbers and QR codes, you must demonstrate that your integration works correctly. That demonstration happens in the sandbox.
The sandbox is FBR's testing environment. It looks and behaves like production, accepts the same JSON payload format, validates the same fields, and returns the same response codes, but no submission counts against your taxpayer record. You can submit thousands of test invoices without consequence. Once you are confident the integration works, you switch to production and your live invoices start flowing.
To access the sandbox you need a sandbox Bearer token. This token is issued by the IRIS portal at iris.fbr.gov.pk and is valid for 5 years. You include it in the Authorization header of every API call you make to the sandbox endpoint.
Sandbox vs Production: When to Use Each
Two tokens, two environments, one process:
- Sandbox token: used against
postinvoicedata_sb. Test invoices, no tax record impact, no penalties for malformed payloads. This is where you spend the first one to two weeks. - Production token: used against
postinvoicedata. Real invoices, real 22-digit FBR invoice numbers, real PRAL verification codes printed on the customer's PDF.
Both tokens are obtained through the same IRIS workflow. You typically request the sandbox token first, integrate and test, then come back and request the production token once your sandbox testing demonstrates clean submissions. Some businesses request both at the same time and use the sandbox until ready, which is also acceptable.
Prerequisites Before You Request Your Token
Before you log into IRIS to request the token, make sure you have the following ready:
- A valid NTN or CNIC. Companies and AOPs use the 7-digit NTN. Sole proprietors use their 13-digit CNIC.
- An IRIS portal account. If you have never filed a return through IRIS, you need to register first and complete the e-enrolment process.
- STRN if sales tax registered. If your business is registered for sales tax, your STRN is also required.
- The public IP address of the server that will call the FBR API. PRAL whitelists IPs at the network level. If you are using a cloud-based platform like Tax It, the platform's IP will be whitelisted on your behalf. If you are integrating directly, gather your static outbound IP before starting.
- An authorized contact. The person logging into IRIS must have authority to bind the business to the FBR integration.
Step-by-Step: Getting Your FBR Sandbox Token
Plan for about 30 to 60 minutes of focused time inside IRIS, plus a wait of up to 2 hours for PRAL to provision your token and whitelist your IP.
Step 1: Log Into IRIS
Open iris.fbr.gov.pk in a desktop browser. Mobile browsers occasionally have issues with the digital invoicing screens, so use a laptop or desktop. Enter your NTN/CNIC and password, complete the captcha, and sign in.
Step 2: Navigate to the Digital Invoicing Section
From the IRIS dashboard, look for the Sales Tax menu or the dedicated Digital Invoicing tab. The exact menu label has shifted over the past two years as FBR has reorganized the portal, so use the search bar at the top of IRIS and type "digital invoicing" if you cannot find it directly.
Step 3: Submit the Integration Request
Inside the Digital Invoicing section you will see an option to request integration or obtain a sandbox token. The form asks for:
- Your business details (pre-filled from your IRIS profile)
- Your integration approach (in-house build, licensed integrator, or cloud platform)
- The static public IP address you want whitelisted
- A contact email and phone number
Submit the form and note the reference number IRIS gives you. You will need this if you contact FBR support to check status.
Step 4: Wait for PRAL to Provision the Token
Pakistan Revenue Automation Limited (PRAL) is the technical operator behind FBR's digital systems. PRAL reviews the request, provisions your sandbox token, and whitelists your submitted IP. Provisioning typically completes within 2 hours during business hours. You will receive an email when the token is ready.
Step 5: Retrieve Your Bearer Token from IRIS
Once provisioning is complete, log back into IRIS and navigate to the same Digital Invoicing section. Your sandbox Bearer token will be displayed as a long alphanumeric string. Copy it carefully — every character matters. The token is valid for 5 years from issue.
Security note: Treat the Bearer token like a password. Anyone holding it can submit invoices on behalf of your business in the sandbox. Store it in your platform's encrypted settings, never paste it into chat or email, and rotate it if a team member with access leaves.
How to Use the Sandbox Token
Once you have the token, you have two paths.
Path A: Use a Cloud Platform (Recommended for SMEs)
If you are using a platform like Tax It, you simply paste the token into your FBR settings page, set the mode to Sandbox, and you are ready to test. The platform handles the JSON payload construction, signs the request with the Bearer token, parses the FBR response, and shows you a clear pass or fail result. You can submit your first test invoice within five minutes of pasting the token.
See how Tax It's onboarding wizard handles this exact step in three clicks.
Path B: Build Your Own Integration
If you are building in-house, every API call to the sandbox endpoint needs:
- URL:
https://gw.fbr.gov.pk/di_data/v1/di/postinvoicedata_sb - Method: POST
- Authorization header:
Bearer your_sandbox_token_here - Content-Type:
application/json - Body: A JSON payload conforming to the FBR DI Technical Specification V1.12, including seller and buyer details, line items with HS codes, tax breakdowns, and the invoice reference number.
FBR's response will include an invoiceNumber field if validation passes, or an error code and message if it fails. Common first-attempt failures are covered in the section below.
Common Errors and How to Fix Them
Error 0001: Invalid Bearer Token
Most likely cause: you copied an extra space or pasted the token with line breaks. Re-copy from IRIS and verify the string is exactly the length IRIS shows.
Error 0012: Buyer Registration Type Invalid
In most real cases this means your source IP is not whitelisted yet. PRAL whitelisting takes up to 2 hours after token issue. Wait and retry. If the error persists after 2 hours, confirm the IP you submitted in IRIS matches your actual outbound IP using a tool like ifconfig.me.
Error 0104: Sales Tax Mismatch
FBR validates that the sum of your line item taxes equals the invoice-level tax field. The fix is to round each line item to 2 decimal places before summing. FBR uses half-up rounding.
Error 0510: Buyer Province or Address Missing
For unregistered buyers some scenarios still require the province and address fields. Populate them with the seller's province and address as a default if the buyer has not provided their own.
Moving from Sandbox to Production
Once you have completed a clean sandbox test run, you are ready to request the production token through the same IRIS workflow. The production token is a separate Bearer string. You change your platform's mode from sandbox to production, paste the production token, and your next invoice goes into the real FBR system. Tax It supports mock, sandbox, and production modes side by side, so you can switch between them per company without re-deploying anything.
Frequently Asked Questions
How long does it take to get an FBR sandbox token?
From submitting the IRIS request to receiving your token, expect 2 hours on a business day. Outside business hours the wait can stretch to the next morning. The token request itself takes 10 to 15 minutes inside IRIS.
Is the FBR sandbox token free?
Yes. FBR does not charge for token issue. PRAL whitelisting is also free. You will only incur costs for the integration software you build or subscribe to.
Can I test FBR digital invoicing without a sandbox token?
Yes, with a platform that supports mock mode. Tax It's mock mode generates realistic-looking FBR invoice numbers and QR codes without contacting FBR, which is useful for demos and onboarding before your real sandbox token arrives.
What happens if my sandbox token expires?
The sandbox token is valid for 5 years. When it nears expiry, log back into IRIS and request a renewal. Plan for a small buffer before your 5-year mark to avoid any service interruption.
Do I need a separate token for each branch?
No. One sandbox token covers the entire NTN. If you have multiple branches under the same NTN, the same token authenticates submissions for all of them. The branch-level distinction happens in the invoice payload.
What is the difference between PRAL and FBR?
FBR is the regulator. PRAL is the technical operator of FBR's digital systems, including the gateway that processes your invoice submissions. When something is wrong at the gateway level, PRAL is who you contact.
Skip the Build, Use Tax It
Tax It handles the FBR integration for you so you can focus on running your business. Paste your sandbox token, run a few test invoices, switch to production. Pakistani businesses are already submitting FBR-compliant invoices from PKR 2,999 per month.
See pricing → or calculate your FBR non-compliance exposure →