How to get your PRAL token and pass FBR sandbox scenarios

A PRAL token is the bearer credential FBR's Digital Invoicing API uses to recognize your business; it belongs to your NTN or CNIC, not to any software vendor, and is valid for 5 years once issued. You get one by nominating PRAL as your licensed integrator inside IRIS, registering your software details, and passing a set of standard test invoices FBR calls sandbox scenarios. None of this costs anything, and once it is done, any invoicing software, including InvoiceGuru, can submit invoices to FBR on your behalf using that token.

This guide walks through the whole path in order: what you need before you start, each IRIS step, what "passing" a sandbox scenario actually means, and what changes once you move to production.

Before you start: prerequisites

You need three things in place before you open IRIS:

1. An active sales tax registration. You need a valid STRN and working IRIS login (registration number and password). If you are not sure whether you are in scope for digital invoicing at all, our complete guide to FBR digital invoicing covers who must integrate and by when.
2. Basic technical details ready. A technical contact person, their mobile number and email, and the name of the software or ERP you will actually invoice with (for example, "InvoiceGuru"), plus whether it runs in the cloud or on premises and its version number.
3. A CRM login for support. FBR's Digital Invoicing CRM (a separate support portal from IRIS itself) needs an email and password you set during registration, used later if a scenario fails and you need to raise a support ticket.

You do not need any of this pre-approved. IRIS collects all of it in one continuous registration flow.

Step 1: nominate PRAL as your licensed integrator

Log in to IRIS with your registration number and password, then find the Digital Invoicing option from your dashboard. You will land on an "Integration Mode" screen with two paths: API Integration (what you want) and Manual Invoice Generation (a fallback for businesses issuing very few invoices, not covered here).

Inside API Integration, IRIS asks you to choose a licensed integrator. Select the option to proceed with PRAL. Per FBR's own Digital Invoicing user manual, this is the point where "PRAL will provide free of cost licensed integrator services along with sandbox testing," compared with other licensed integrators, who may charge a fee. Submit, and IRIS moves you into the Technical Details tab.

This single step is what satisfies Rule 150XF, the rule that requires PRAL to integrate any registered person free of cost on demand. It is also independent of whatever invoicing software you actually plan to use day to day, which is the next step.

Step 2: register your ERP or system provider

The Technical Details form is where you name the software that will actually send invoices. IRIS asks for:

• Technical contact person, mobile number, and email
• The ERP/System Provider name (your invoicing software, for example "InvoiceGuru")
• Software type: cloud or on premises
• Software version
• A CRM user ID and password for the Digital Invoicing support portal

You also specify your business nature (you can select more than one) and a single sector. This combination is what determines which sandbox scenarios apply to you in the next step, since FBR does not require every business to test all 28 scenarios, only the ones relevant to what it actually sells.

Step 3: generate your sandbox credentials

After Technical Details, IRIS asks for IP whitelisting information: your hosting server's company name, country, and up to three IP addresses (or a spreadsheet upload if you have more). Submit it, and per FBR's own manual, "the PRAL Data Centre will accept or reject the IPs submitted by the taxpayer within 2 working hours," which then automatically unlocks the Sandbox Environment tab.

From there, IRIS shows you a sandbox security token, sample JSON payloads, and sample code. This sandbox token is what your software (or a tool like Postman, if you are testing manually) uses to authenticate against FBR's sandbox endpoint while you work through the required scenarios.

Step 4: work through the required sandbox scenarios

FBR's scenario list, numbered SN001 through SN028, covers everything from standard-rate goods sales to industry-specific cases like steel re-rolling, telecom services, and petroleum products. You do not need to pass all 28: IRIS only shows the scenarios that match the business nature and sector combination you selected in step 2. A trading business selling standard-rate goods to registered and unregistered buyers, for instance, is typically looking at a handful of trading scenarios (SN001 and SN002 plus a few related ones, and the retailer scenarios SN026 to SN028 if it is registered as a retailer), not the cotton-ginning or ship-breaking scenarios. Check the exact set IRIS shows you against the scenario table in the DI API technical documentation, since the list depends on your business nature and sector.

"Passing" a scenario means submitting a correctly formatted invoice JSON for that scenario ID and getting back a valid response with a unique invoice number, rather than a rejection. Each submission is a real test of your data mapping: seller and buyer NTN/CNIC, HS codes, unit of measure, tax rates, and the specific scenario ID all have to be right, not just present. If a submission comes back rejected, fix the field the error message points to and resubmit; there is no limit on retries in the sandbox.

Once every scenario relevant to your business nature and sector has a successful submission, FBR's system automatically generates a production token behind the scenes. You do not request it separately.

Step 5: request your production bearer token

By the time you have cleared the required scenarios, the production token already exists; IRIS's Production Environment tab shows it to you along with your production API URL details. This token is the one that matters going forward: a 5-year bearer credential, tied to your NTN or CNIC, that any invoicing software submits in the Authorization header of every real invoice from this point on.

Keep this token somewhere your invoicing software can read it securely. It does not need to be regenerated invoice by invoice or month by month; it is a long-lived credential by design, precisely so businesses are not stuck re-running sandbox scenarios every year.

Step 6: production IP whitelisting and going live

Production traffic is where IP whitelisting is enforced without ambiguity: FBR only accepts invoice submissions from the server IP addresses you registered. If your invoicing software runs from a cloud provider or a hosted platform rather than your own office network, use that platform's outbound IP, not your office connection, since that is the address FBR's servers will actually see.

Once your IP is confirmed and you are using the production token and production API URL, you are live: every invoice you submit gets checked in real time and comes back accepted, with a unique FBR invoice reference number and QR code, or rejected with a specific error to fix. This is also the point where the penalties for getting invoicing wrong actually start to bite, so it is worth testing a handful of real invoices carefully before treating the switch as fully complete.

Sandbox vs production at a glance

If a scenario keeps failing

Most sandbox rejections trace back to a handful of causes: a scenario ID that does not match the invoice type you are actually sending, a buyer or seller NTN/CNIC in the wrong digit format, a tax rate that does not match the scenario's expected rate, or a missing field the schema requires even when it looks optional in your own software. Check the exact error message against the field it names before assuming the whole submission is wrong; FBR's rejections are usually specific, not generic. If a scenario genuinely will not clear after several careful attempts, the Digital Invoicing CRM support portal (a separate login from IRIS, using the technical contact email and password you set in step 2) is the right place to raise it, rather than resubmitting the same broken payload repeatedly.

Where InvoiceGuru fits once you have a token

Everything above happens once, inside IRIS, and belongs to your business, not to any software vendor. Once your production token exists, InvoiceGuru uses it to handle the part that would otherwise repeat every single day: building each invoice correctly, submitting it, showing you the FBR response, and keeping a clean record if anything is ever rejected and needs a resubmission. You still own the token and the FBR relationship; the software just automates what happens on top of it. You can see how that looks in practice on InvoiceGuru's homepage.