FBR Digital Invoicing Integration: Complete Guide for Pakistan 2025

Introduction

The Federal Board of Revenue (FBR) Pakistan has mandated digital invoicing for registered taxpayers to improve tax compliance, reduce fraud, and automate the sales tax collection process. This comprehensive guide will walk you through the entire process of integrating your business software or ERP system with FBR's Digital Invoicing System.

Whether you're a software developer building an invoicing solution, a business owner looking to understand the process, or an IT professional tasked with implementing FBR integration, this tutorial covers everything you need to know.

1. Prerequisites

Before you begin the FBR Digital Invoicing integration process, ensure you have the following:

Business Requirements

• Active NTN (National Tax Number): Your business must be registered with FBR
• Sales Tax Registration: Active STRN (Sales Tax Registration Number) is required
• IRIS Portal Access: Valid login credentials for FBR's IRIS portal
• Business Bank Account: Registered with FBR for tax payments

Technical Requirements

• Static IP Address: Your server must have a static IP for whitelisting
• HTTPS Support: SSL certificate for secure communication
• JSON Capability: Your system must handle JSON request/response
• Development Environment: For testing API integration

2. Accessing FBR IRIS Portal

The IRIS (Inland Revenue Information System) portal is FBR's primary online platform for all tax-related services. Here's how to access it:

Figure 1: FBR IRIS Portal Dashboard - Click on "Digital Invoicing" to begin integration

The IRIS dashboard provides access to multiple services. For digital invoicing integration, look for the "Digital Invoicing" option in the top navigation bar. You'll also see other useful sections like:

• Sales Tax Invoice Management: For managing your sales tax invoices
• FBR Maloomat: Tax information and records
• File Your Sales Tax Return: Monthly/quarterly return filing
• Withholding Statement: For withholding tax documentation

3. Digital Invoicing Module

Click on the "Digital Invoicing" button in the IRIS header to access the Digital Invoicing module. This module is specifically designed for businesses that want to integrate their software systems with FBR for automated invoice submission.

What is FBR Digital Invoicing?

FBR Digital Invoicing is a system that allows businesses to:

• Submit invoices electronically in real-time
• Receive instant FBR invoice numbers (IRNM)
• Generate QR codes for invoice verification
• Automate sales tax calculations and reporting
• Maintain compliance with FBR regulations

4. Choosing Integration Mode

FBR offers multiple integration modes based on your business size and technical capabilities:

Figure 2: Choose Integration Mode - Select API Integration for software integration

Available Integration Modes

For this tutorial, we'll focus on API Integration as it provides the most flexibility and automation for businesses with custom software solutions.

5. Selecting Licensed Integrator (PRAL)

FBR requires all API integrations to go through a Licensed Integrator (LI). The Licensed Integrator acts as an intermediary between your software and FBR's systems, ensuring security and compliance.

Why Licensed Integrators?

• Enhanced security and data validation
• Standardized API interface
• Technical support and troubleshooting
• Compliance monitoring

Available Options

Option 1: PRAL (Pakistan Revenue Automation Limited) - Recommended

Option 2: Other Licensed Integrators

You can also choose from other FBR-approved licensed integrators. However, note the following pricing guidelines:

• Maximum charge: Rs. 10/- per invoice
• Monthly retainership option: Rs. 100,000/- per taxpayer
• Annual retainership: Not exceeding Rs. 1,000,000/- per taxpayer

6. API Integration Setup

After selecting your Licensed Integrator, you'll need to configure your API integration settings. This involves providing technical details about your system.

Technical Details Required

API Credentials

After submitting your technical details, FBR will generate:

• Client ID: Unique identifier for your integration
• Client Secret: Secret key for authentication (keep this secure!)
• Sandbox API Endpoint: URL for testing environment

7. IP Whitelisting

FBR requires IP whitelisting as a security measure. Only requests from your registered IP addresses will be accepted by the FBR API.

Steps for IP Whitelisting

8. Sandbox Environment & Testing Scenarios

Before you can submit invoices to FBR's production system, you must successfully complete all required testing scenarios in the Sandbox environment. This ensures your integration is working correctly and handles all invoice types properly.

Figure 3: Sandbox Environment showing 6 test scenarios - All must show "Successful" status

What is the Sandbox Environment?

The Sandbox is a testing environment that mirrors the production system but doesn't affect real tax records. It allows you to:

• Test your API integration without real consequences
• Validate invoice formats and data structures
• Handle different invoice scenarios
• Debug and fix issues before going live

Accessing Sandbox

9. Understanding Test Scenarios

FBR requires you to successfully complete specific test scenarios before production access is granted. Each scenario tests a different type of invoice transaction.

Standard Test Scenarios

Scenario Details Explained

SN001: Goods at Standard Rate to Registered Buyers

This scenario tests B2B transactions where:

• Buyer has valid STRN (Sales Tax Registration Number)
• Standard GST rate of 18% applies
• Input tax credit is claimable by buyer
• Full buyer details required (NTN, STRN, address)

SN002: Goods at Standard Rate to Unregistered Buyers

This scenario tests B2C transactions where:

• Buyer is not registered for sales tax
• CNIC may be required for transactions above threshold
• Standard GST rate applies
• No input tax credit for buyer

SN008: Sale of 3rd Schedule Goods

Third Schedule goods have special tax treatment under Sales Tax Act 1990:

• Different tax rates may apply
• Specific goods listed in 3rd Schedule of Sales Tax Act
• May include items like petroleum, gas, etc.
• Special reporting requirements

SN026-SN028: Retail Consumer Sales

These scenarios test Point of Sale transactions:

• Quick invoice generation for retail
• Cash, card, and other payment modes
• Real-time FBR submission
• QR code generation for verification

Completing Test Scenarios

10. Invoice API Structure

Understanding the API structure is crucial for successful integration. Here's a detailed breakdown of the invoice submission API.

Authentication

FBR API uses OAuth 2.0 for authentication. First, obtain an access token:

POST /auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Response:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600
}

Invoice Submission Request

Submit invoices using the following structure:

POST /api/v1/invoices
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
    "InvoiceNumber": "INV-2025-001234",
    "InvoiceType": 1,
    "InvoiceDate": "2025-12-09",
    "InvoiceTime": "14:30:00",
    "BuyerNTN": "1234567-8",
    "BuyerSTRN": "12-34-5678-901-23",
    "BuyerName": "ABC Company Pvt Ltd",
    "BuyerAddress": "123 Business Street, Karachi",
    "BuyerPhone": "021-1234567",
    "TotalSaleValue": 100000.00,
    "TotalTaxCharged": 18000.00,
    "TotalBillAmount": 118000.00,
    "PaymentMode": 1,
    "Items": [
        {
            "ItemCode": "PROD-001",
            "ItemName": "Product Description",
            "Quantity": 10,
            "UnitPrice": 10000.00,
            "TotalAmount": 100000.00,
            "TaxRate": 18.00,
            "TaxAmount": 18000.00,
            "PCTCode": "85.17"
        }
    ]
}

Invoice Types

Payment Modes

Successful Response

{
    "Status": "Success",
    "FBRInvoiceNumber": "IRNM5440194651731D117607057481749",
    "QRCode": "base64_encoded_qr_code_image",
    "VerificationURL": "https://verify.fbr.gov.pk/verify?inv=IRNM5440...",
    "Message": "Invoice submitted successfully"
}

Error Response

{
    "Status": "Error",
    "ErrorCode": "E1001",
    "ErrorMessage": "Invalid buyer STRN format",
    "Details": "STRN must be in format XX-XX-XXXX-XXX-XX"
}

11. Moving to Production

After successfully completing all sandbox test scenarios, you can request production access.

Production Checklist

Requesting Production Access

Production API Endpoint

Production URL: https://api.fbr.gov.pk/api/v1/ (verify from portal)

12. Best Practices & Tips

Development Best Practices

• Implement Retry Logic: Network issues can cause temporary failures. Implement exponential backoff retry mechanism.
• Store FBR Response: Always save the FBR Invoice Number and QR code returned for each invoice.
• Validate Before Submission: Check all required fields and formats before API call to reduce errors.
• Log Everything: Maintain detailed logs of all API requests and responses for troubleshooting.
• Handle Timeouts: Set appropriate timeout values (30-60 seconds) for API calls.

Business Best Practices

• Train Staff: Ensure all invoice-creating staff understand FBR requirements.
• Regular Reconciliation: Match your invoices with FBR's Invoice Dashboard regularly.
• Backup System: Have a manual entry backup plan if API fails.
• Monitor Dashboard: Check FBR's Invoice Dashboard for any rejected or pending invoices.

Security Best Practices

• Secure Credentials: Store Client ID and Secret in environment variables or secure vault.
• Use HTTPS: All API communication must be over HTTPS.
• IP Restriction: Only make API calls from whitelisted IPs.
• Token Management: Refresh access tokens before expiry; don't hardcode tokens.

13. Common Errors & Troubleshooting

Authentication Errors

Invoice Submission Errors

Connection Errors

14. Frequently Asked Questions

General Questions

Q: Is FBR digital invoicing mandatory?

A: Yes, for certain categories of businesses as notified by FBR. Tier-1 retailers, manufacturers above threshold, and certain service providers must integrate. Check latest SROs for specific requirements.

Q: What is the cost of integration?

A: Using PRAL as Licensed Integrator is free. Other LIs can charge maximum Rs. 10 per invoice or offer monthly/annual packages.

Q: How long does the integration process take?

A: Typically 2-4 weeks including sandbox testing. Timeline depends on your technical readiness and testing completion speed.

Technical Questions

Q: Can I use dynamic IP addresses?

A: No, FBR requires static IP addresses for whitelisting. You must use a server with a fixed IP.

Q: What happens if FBR API is down?

A: Implement a queue system to store invoices locally and submit when API is available. Have a manual backup process for critical invoices.

Q: Can I cancel/modify a submitted invoice?

A: You cannot modify a submitted invoice. You must issue a Credit Note to reverse it and then issue a new corrected invoice.

Q: How do I handle returns?

A: Issue a Credit Note (Invoice Type 3) referencing the original invoice number. This will adjust the tax liability.

Compliance Questions

Q: What is the penalty for non-compliance?

A: Penalties vary but can include fines, suspension of STRN, and other enforcement actions. Consult FBR regulations for specific penalties.

Q: Do I need to print QR codes on invoices?

A: Yes, FBR-compliant invoices must display the QR code returned by FBR API. This allows verification of invoice authenticity.

Conclusion

FBR Digital Invoicing integration may seem complex initially, but following this step-by-step guide will help you navigate the process successfully. Remember the key steps:

1. Access IRIS portal and navigate to Digital Invoicing
2. Choose API Integration mode
3. Select PRAL as your Licensed Integrator (free option)
4. Configure technical details and whitelist your IPs
5. Complete all sandbox test scenarios
6. Request and receive production credentials
7. Go live with real invoice submission

Proper FBR integration not only ensures compliance but also automates your tax reporting, reduces manual errors, and provides real-time visibility into your sales tax obligations.