Sandbox Testing

Sandbox testing lets you run real FBR validation scenarios against test invoices without affecting your live data or consuming production credits. This is a required step before you can get a production token.

Enable sandbox mode

Before running any tests, confirm that your organisation is set to sandbox mode and that the sandbox token is correctly entered.

1. Open Invoices → select your organisation → click the settings cog → Integrations tab.
2. Check that the Sandbox Token field contains your token. If it is empty, paste the token you retrieved from the IRIS portal and click Save.
3. Confirm that sandbox mode is active. The dashboard banner should display "Sandbox active" when your organisation is correctly configured for sandbox testing.

If the sandbox banner does not appear, double-check that your organisation is set to sandbox-only mode on the Organisations page. An organisation in active mode will attempt production submissions instead of sandbox calls.

Run sandbox testing

Once sandbox mode is confirmed, you can run the full suite of FBR validation scenarios directly from TaxConnect.

1. Navigate to Invoices → select your organisation → click the settings cog → Integrations tab.
2. Click the Run Sandbox Testing (live) button. This action is not a dry run — TaxConnect streams each scenario to the live FBR sandbox endpoint in real time.
3. Watch the progress panel as each scenario is tested. The interface shows a running status for every test, updating as the FBR sandbox returns a response.
4. Each scenario displays a pass or fail result. For any failures, click the entry to expand the response details — the error message from the FBR API will help you identify what went wrong.

The full test run typically completes within a few minutes, depending on the number of scenarios and the current responsiveness of the FBR sandbox environment.

What scenarios are tested

TaxConnect runs a comprehensive set of FBR-defined scenarios during sandbox testing. Each scenario represents a real-world invoicing situation that your integration must handle correctly.

• Standard rate sales — Invoices with the standard FBR sales tax rate applied. This is the most common scenario and validates that your basic invoice structure is correct.
• Exempt supplies — Invoices where the goods or services are exempt from sales tax. The system checks that exempt items are flagged correctly and no tax is calculated.
• Reduced rate supplies — Invoices using a reduced tax rate (for example, 5% instead of the standard rate). This validates that your tax mapping correctly identifies and applies reduced rates.
• Debit and credit notes — Scenarios that test the creation of debit notes (increasing the amount originally invoiced) and credit notes (reducing the amount). These must reference the original invoice and carry the correct note type.
• Other FBR-defined scenarios — Additional test cases defined by the FBR schema, including mixed-rate invoices, zero-rated supplies, and edge cases that the FBR sandbox validates against.

Each scenario is tested independently. A failure in one scenario does not prevent the others from running, so you can identify exactly which areas need attention without re-running the entire suite.

After testing completes

When the sandbox test run finishes, TaxConnect displays a summary screen showing the results for every scenario.

1. Review the passed and failed counts in the summary panel. A green checkmark indicates the scenario was accepted by the FBR sandbox; a red cross indicates a rejection.
2. TaxConnect shows a notification: check IRIS for your production token. This confirms that your sandbox results have been recorded and you can proceed to the production setup phase.
3. If any scenarios fail, review your tenant settings and tax mappings. Common causes include incorrect tax rate mappings, missing mandatory fields, or mismatched invoice line structures. Correct the issues and re-run the sandbox test.

You can re-run sandbox testing as many times as needed. Each run is independent and does not carry over state from previous attempts. Sandbox submissions do not count toward your invoice credit limit, so there is no cost associated with repeated testing.