Pakistan Digital Invoicing Solution

[Syed_Salman_Ali]

FBR’s “Debit Note” in Simple Words:

Imagine you’re a shop owner in Pakistan. You sold a fridge, but later realized you charged the customer too little, or maybe they decided to buy an extended warranty you forgot to add to the first bill.

The FBR Debit Note is simply YOU (the seller/supplier) sending an official “Oops, you owe me more!” note to your customer (the buyer).

• Who sends it? The Seller (Supplier).
• Who gets it? The Buyer (Customer).
• Why? To increase the money the buyer owes you for something you already sold them.

And yes, as the seller, you’re the one responsible for telling the FBR about this “more money” note. The FBR then makes sure the customer also sees it in their tax records.

Is it like “Debit Note” in Manager.io?

NO, NOT AT ALL! This is the biggest point of confusion.

• FBR Debit Note: It’s the SELLER asking for MORE money from the buyer.
• Manager.io Debit Note (and most general accounting): It’s typically the BUYER telling the seller they owe LESS money (e.g., because they returned something).

So, while they share the name “Debit Note,” their purpose and who issues them are completely opposite depending on whether you’re talking about FBR’s sales tax rules or general accounting software.

Think of it this way: For FBR, a Debit Note means “add to the bill.” For Manager.io, it usually means “reduce the bill.”

[shahabb]

So again its just a Sales Invoice but with different title.

[Ealfardan]

@Mabaega, this seems like the same Debit Note concept in KSA Phase II eInvoice.

[Mabaega]

Alright, the Debit Note in this context refers to a sales invoice that includes a reference to a previously submitted invoice.

This means we will need two new custom fields to record the type of sale and the FBR Invoice Number of the previously submitted invoice.

=

FBR Extension has been updated to version 25.07.09.004

• Added support for Debit Note

[uzair94]

how to run these scripts?

[Mabaega]

That’s just an example script for creating or replacing a custom field in the Manager.

If you are developing an application using an AI assistant, you can ask the AI to apply it to your project.

[uzair94]

Just sharing a discovery that cleared up our validation issues:

• Token is hard-linked to the SellerNTN field. If the token and NTN don’t match, your JSON will be rejected at the submission stages.
• Generate the token from the same IRIS login that owns the Seller NTN. Mixing tokens from one NTN with payloads for another won’t work.

[Mabaega]

And how exactly is Sale Type related to:

• the type of customer (Registered / Unregistered),
• the use of HS Code and Item Description,
• and the selected Scenario ID?

I still haven’t fully understood the relationships among these fields.

For now, I’m deriving the Sale Type from the Tax Code Name that’s already set by default in Manager for Pakistan.
However, I’ve noticed that the same Tax Code Name doesn’t work with different customer types. Similarly, the Scenario ID also seems to depend on the Tax Code Name being used.

Could someone clarify how these elements are meant to work together?

I’m sorry if I’m asking too many questions.
At the moment, I’m only working based on the provided guide, and I don’t have direct access or a clear understanding of how things are structured or behave in the actual FBR portal.
That’s why I really appreciate any insights or examples you can share.

[uzair94]

1. Scenario IDs — Why They Matter

1. Assigned at Token Request:

• When you request a sandbox token, FBR asks for your business activity (Manufacturer, Trader, or Service Provider).
• Based on that selection, the system returns one or more scenario IDs (e.g., SN001, SN002, …).

2. Purpose:

• Each scenario ID defines a specific kind of test invoice (e.g., local sale, export sale, return, etc.).
• All scenarios linked to your activity must pass validation. Only then will IRIS automatically issue your production token.

3. Bottom line: Scenario IDs are only about sandbox testing. They don’t appear in live submissions once you’re in production.

---

2. HS Code Database

• FBR supplies an HS-code lookup in the technical manual/dataset.
• The code you use should be consistent with the item description; mismatches often trigger 0046 – Provide rate.or similar errors.
• Tip: Validate your HS codes locally against the provided list before calling the API to save round-trips.

---

3. Customer Type Rules

CustomerType	Required Field	Notes
REGISTERED	Buyer’s NTN (or CNIC for individuals)	Must be a valid, real registration number—otherwise validation fails.
UNREGISTERED	No NTN/CNIC required	Omit the buyer registration fields entirely.

If you mark a buyer as REGISTERED but skip their NTN/CNIC, the API will throw an error asking for the missing info.

---

4. Practical Workflow Checklist

1. Request sandbox token → receive scenario IDs.
2. Generate test invoices for each scenario ID, ensuring:

• Correct HS codes
• Accurate customer NTN/CNIC if CustomerType = REGISTERED

3. Run /validateInvoiceSB until every scenario passes.
4. After all scenarios succeed, IRIS auto-issues your production token linked to your Seller NTN.

[Ealfardan]

The way I understand it, Scenario is a Code for Sale Type, this can be understood from the 1:1 correspondence between the two fields.

Sale Type itself is either analogous to Manager’s Tax Codes or Reporting Categories, I say this for two main reasons:

1. From the above list of Scenarios/Sale Types, we can clearly see the Tax categories for Goods at Standard Rate (SN001 & SN002) Exempt (SN006) and Zero-rated (SN007) along with other distinct categories for tax reporting.

2. Furthermore, Sale Type applies on item level, much like a Tax Code.
   

   

However, we must know if there are multiple tax rates for each Sale Type

I asked a similar question earlier in order to understand how to structure the data.

I believe this is the answer @Mabaega is looking for.

If @Mabaega allows me to rephrase the question:

Let’s say we have the SN019 which corresponds to Sale Type Services. Under this Sale Type there are 211 HS Codes according to FBR.

Now, the million dollar question is this:

Do all 211 HS Codes under SN019 all have the same tax rate (Tax Code)? Or is it possible to have different rates for different services?

If there are multiple tax rates per Scenario/Sale Type, then these are Reporting Categories.

If not, then Scenario/Sale Type are Tax Codes

[Ealfardan]

Giving this more thought

@Mabaega

However, I’ve noticed that the same Tax Code Name doesn’t work with different customer types. Similarly, the Scenario ID also seems to depend on the Tax Code Name being used

Actually, I made the tax code to match the Sale Type, this could be useful, but I can see the issue here.

Namely, SN0026, 27 & 28 only work for retail, which more or less imply Unregistered customer type – but not necessarily.

A registered customer could buy from a retail store and a wholesale business could sell to unregistered customers.

This got me thinking that Tax Code Name could be changed to a more descriptive, e.g. SN0026 could read Retail Goods at Standard Rate.

In fact, since “Standard rate” could change at any time, I think it’s better to make Sale Types correspond to Reporting Categories, however, then we will have to keep Scenario under Tax Code since we cannot have Custom Fields under Reporting Categories.

@Mabaega, @lubos,
What are your thoughts on this? Should I go ahead and make the changes?

[lubos]

@Ealfardan

What are your thoughts on this? Should I go ahead and make the changes?

Go ahead with what you think could work. I’m working towards making localizations more forgiving in a way that if change is made to localization server, it won’t affect existing businesses.

[Ealfardan]

Done,

Now:

1. Sale Type is the Reporting Category
2. Tax Code Names are distinct and more meaningfull

[Mabaega]

Thank you, @uzair94, your explanation really helped me understand the key points.

@Ealfardan
Yes, it seems that Sale Type would be more appropriate to use as a category rather than mapping it directly from the Tax Code Name.
But we still need to hear from Manager users in Pakistan about how they have been using Tax Codes so far in practice.

[Syed_Salman_Ali]

Dear Team, Yellow Highlighted info required,

[uzair94]

• You don’t need a separate “license” to integrate with FBR’s Digital Invoicing (DI) system.
• What you do need is a sandbox/production token issued by PRAL (the FBR Technology wing) under the “Integrator” role.
• Once PRAL grants your token, you use it—tied to your Seller NTN—for both validation and live submissions. That’s the whole requirement.

In short: skip the licensing paperwork; focus on getting your integrator token from PRAL and start testing.

[uzair94]

Hi @Mabaega

Good news: I’ve successfully passed several DI sandbox scenarios using my custom app, and I already have the validated JSON payloads for all remaining scenarios.

Could you advise on the best way to share these files with you? I’m happy to upload them via your preferred channel (GitHub Gist, Google Drive, email attachment—whatever works).

I’ll also test the Manager application with my current token later today and report back.

Thanks in advance for your guidance!

[uzair94]

Hey @Mabaega,

I’m running into a validation snag that might help others, too. Here’s the payload/response snapshot:
{
“success”: true,
“data”: {
“status”: “Success”,
“httpStatus”: 200,
“endpoint”: “https://gw.fbr.gov.pk/di_data/v1/di/validateinvoicedata_sb”,
“environment”: “Sandbox”,
“timestamp”: “2025-07-11T09:40:51.0742218Z”,
“response”: {
“dated”: “2025-07-11 14:40:39”,
“validationResponse”: {
“statusCode”: “01”,
“status”: “Invalid”,
“errorCode”: “0012”,
“error”: "Provide Buyer Registration Type. Registered / Unregistered ",
“invoiceStatuses”: null
}
}
},
“message”: “Invoice successfully validated with PRAL FBR”
}

What I’ve noticed

• Manager app auto-generates the field as “RegistrationType”: “UnRegistered” (capital R mid-word).
• FBR expects exactly Registered or Unregistered (all lowercase after the first letter).
• The mismatched casing is triggering errorCode 0012.

[Mabaega]

Thank you @uzair94 for sharing the sample JSON data from the portal. It was very helpful.

I have successfully validated the invoice.
Here are some important points that users need to understand for now:

• You must use real NTN/CNIC values during testing, both for the Seller/Business Details and the Buyer/Customer.
• The Sale Type is case-sensitive. You cannot rely on the default Tax Code Name set in Manager.

[Mabaega]

@Ealfardan

Done,

Now:

1. Sale Type is the Reporting Category
2. Tax Code Names are distinct and more meaningfull

This might help in setting up default Tax Codes for Pakistan.
The applicable Tax Rate heavily depends on the Transaction Type / Sale Type.

Using the RateDesc as the name of the Tax Code might simplify things and make it easier for users to select the correct one.

As for using Sale Type as a category, it might be a good approach for supporting ReportingCategoriesForTaxCodes and Report Transformations — although I must admit I haven’t fully understood the concept yet.

Date : “24-Feb-2024”

SaleTypeID	SaleTypeDesc	RateID	RateDesc	RateValue	ScheduleID	ScheduleDesc
75	Goods at standard rate (default)	728	18%	18.00
24	Goods at Reduced Rate	436	0.5%	0.50	393	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	413	1%	1.00	372	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	419	1.5%	1.50	375	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	126	2%	2.00	365	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	434	3%	3.00	392	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	424	4.5%	4.50	388	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	109	5%	5.00	364	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	109	5%	5.00	371	EIGHTH SCHEDULE Table 2
24	Goods at Reduced Rate	175	7%	7.00	366	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	415	7.5%	7.50	373	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	261	8%	8.00	367	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	329	8.5%	8.50	131	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	129	10%	10.00	363	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	129	10%	10.00	370	EIGHTH SCHEDULE Table 2
24	Goods at Reduced Rate	286	12.5%	12.50	368	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	623	12.75%	12.75	397	587(I)/2017
24	Goods at Reduced Rate	623	12.75%	12.75	428	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	432	13%	13.00
24	Goods at Reduced Rate	747	15%	15.00	451	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	708	16%	16.00	425	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	730	17%	17.00	442	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	732	18%	18.00	443	EIGHTH SCHEDULE Table 1
24	Goods at Reduced Rate	722	Rs.700/MT	700.00	435	EIGHTH SCHEDULE Table 1
80	Goods at zero-rate	131	0%	0.00	106	327(I)/2008
80	Goods at zero-rate	131	0%	0.00	386	FIFTH SCHEDULE
80	Goods at zero-rate	131	0%	0.00	396	SECTION 49
80	Goods at zero-rate	131	0%	0.00	65	Section 4(b)
85	Petroleum Products	654	0%	0.00	405	1579(1)/2021
85	Petroleum Products	654	0%	0.00	429	321(I)/2022
85	Petroleum Products	645	0.20%	0.20	404	1450(I)/2021
85	Petroleum Products	680	0.46%	0.46	407	1579(1)/2021
85	Petroleum Products	680	0.46%	0.46	412	1604(I)/2021
85	Petroleum Products	653	1.43%	1.43	401	1450(I)/2021
85	Petroleum Products	677	1.63%	1.63	409	1604(I)/2021
85	Petroleum Products	685	2.5%	2.50	417	88(I)/2022
85	Petroleum Products	681	2.70%	2.70	416	01(I)/2022
85	Petroleum Products	681	2.70%	2.70	420	88(I)/2022
85	Petroleum Products	643	2.74%	2.74
85	Petroleum Products	641	3.67%	3.67
85	Petroleum Products	682	4.77%	4.77	413	01(I)/2022
85	Petroleum Products	686	5.44%	5.44	418	88(I)/2022
85	Petroleum Products	644	6.70%	6.70	403	1450(I)/2021
85	Petroleum Products	652	6.75%	6.75	402	1450(I)/2021
85	Petroleum Products	650	6.84%	6.84
85	Petroleum Products	655	7.20%	7.20	406	1579(1)/2021
85	Petroleum Products	678	7.37%	7.37	410	1604(I)/2021
85	Petroleum Products	639	7.56%	7.56
85	Petroleum Products	679	8.19%	8.19	411	1604(I)/2021
85	Petroleum Products	683	8.30%	8.30	415	01(I)/2022
85	Petroleum Products	683	8.30%	8.30	419	88(I)/2022
85	Petroleum Products	684	9.08%	9.08	414	01(I)/2022
85	Petroleum Products	642	9.15%	9.15
85	Petroleum Products	640	10.07%	10.07
85	Petroleum Products	651	10.32%	10.32
85	Petroleum Products	648	10.54%	10.54
85	Petroleum Products	647	10.77%	10.77
85	Petroleum Products	649	11.64%	11.64
85	Petroleum Products	286	12.5%	12.50	368	EIGHTH SCHEDULE Table 1
85	Petroleum Products	638	15.44%	15.44
85	Petroleum Products	646	16.40%	16.40
85	Petroleum Products	728	18%	18.00
62	Electricity Supply to Retailers	147	5%	5.00
62	Electricity Supply to Retailers	110	7.5%	7.50
129	SIM	411	Rs.250	250.00	376	NINTH SCHEDULE
77	Gas to CNG stations	728	18%	18.00
122	Mobile Phones	627	Rs.10	10.00
122	Mobile Phones	736	18%	18.00	445	NINTH SCHEDULE
122	Mobile Phones	735	25%	25.00	446	NINTH SCHEDULE
122	Mobile Phones	621	Rs.130	130.00
122	Mobile Phones	619	Rs.200	200.00
122	Mobile Phones	397	Rs.1680	1,680.00	379	NINTH SCHEDULE
122	Mobile Phones	398	Rs.1740	1,740.00	380	NINTH SCHEDULE
122	Mobile Phones	399	Rs.5400	5,400.00	381	NINTH SCHEDULE
122	Mobile Phones	409	Rs.9270	9,270.00	382	NINTH SCHEDULE
25	Processing/Conversion of Goods	269	0%	0.00
25	Processing/Conversion of Goods	185	3%	3.00
25	Processing/Conversion of Goods	54	5%	5.00
25	Processing/Conversion of Goods	728	18%	18.00
23	3rd Schedule Goods	728	18%	18.00
23	3rd Schedule Goods	746	25%	25.00	450	297(I)/2023-Table-I
21	Goods (FED in ST Mode)	132	0.5%	0.50
21	Goods (FED in ST Mode)	128	8%	8.00
21	Goods (FED in ST Mode)	402	17%	17.00
22	Services (FED in ST Mode)	41	8%	8.00
22	Services (FED in ST Mode)	22	16%	16.00
22	Services (FED in ST Mode)	92	17%	17.00
22	Services (FED in ST Mode)	23	19.5%	19.50
22	Services (FED in ST Mode)	42	200/bill	200.00
18	Services	28	Exempt	0.00
18	Services	280	0%	0.00	387	FIFTH SCHEDULE
18	Services	280	0%	0.00	438	ICTO
18	Services	280	0%	0.00	426	ICTO TABLE II
18	Services	422	5%	5.00	452	ICTO TABLE I
18	Services	422	5%	5.00	427	ICTO TABLE II
18	Services	614	15%	15.00	434	ICTO TABLE I
18	Services	22	16%	16.00
18	Services	92	17%	17.00
18	Services	430	18.5%	18.50
18	Services	281	50/SqY	50.00
18	Services	282	100/SqY	100.00
18	Services	717	Rs.1000	1,000.00	431	ICTO TABLE II
81	Exempt goods	133	Exempt	0.00	383	6th Schd Table I
81	Exempt goods	133	Exempt	0.00	384	6th Schd Table II
81	Exempt goods	133	Exempt	0.00	385	6th Schd Table III
81	Exempt goods	133	Exempt	0.00	439	Eighth Schedule Table 1
81	Exempt goods	133	Exempt	0.00	391	NINTH SCHEDULE
82	DTRE goods	134	DTRE	0.00
130	Cotton ginners	728	18%	18.00
132	Electric Vehicle	625	1%	1.00	399	6th Schd Table III
132	Electric Vehicle	625	1%	1.00	400	EIGHTH SCHEDULE Table 1
134	Cement /Concrete Block	629	Rs.2	2.00
134	Cement /Concrete Block	631	Rs.3	3.00
134	Cement /Concrete Block	633	Rs.5	5.00
134	Cement /Concrete Block	635	Rs.10	10.00
84	Telecommunication services	343	17%	17.00
84	Telecommunication services	146	18.5%	18.50
84	Telecommunication services	181	19.5%	19.50
123	Steel melting and re-rolling	728	18%	18.00
125	Ship breaking	745	18%	18.00
115	Potassium Chlorate	734	18% along with rupees 60 per kilogram	18.00	444	EIGHTH SCHEDULE Table 1
138	Non-Adjustable Supplies	727	0%	0.00	440	Eighth Schedule Table 1
139	Goods as per SRO.297(	)/2023	742	25%	25.00	448
139	Goods as per SRO.297(	)/2023	742	25%	25.00	449