API Pricing Image

Overview

Use this API to prepare TDS return by posting a job to generate the TXT file

Problem

Businesses need to file their TDS returns quarterly to be TDS compliant.
Businesses that deduct TDS under sections 192 (Salary), 194 (Dividends), 194O (E-Commerce Transactions) & 194S (Transfer of Virtual Digital Assets) have volumetric transactions.
This makes reporting prone to fat-fingering and other errors that can delay the process of filing the TDS Return and can incur interest & penalty costs.

Solution

The API will automate the generation of the TXT file which is required to file quarterly TDS returns.
Use the PUT request on the presigned_url to upload TDS deduction-related information.
Get job_id to obtain the TXT file using the Job status API.
You can also configure Postbacks to get notified when the Job is done.

Endpoint

HTTP Method	Resource
`POST`	tds-reporting/deductors/{tan}/tdsrs/{form}/async

Request

Follow the below guidelines to pass TAN, form in the path parameter, and financial year, quarter, previous RRR number, and filing type in the query parameter.

Path Parameter

Param	Type	Description	Example
tan	`string`	TAN of deductor	PDES03028F
form	`enum`	TDS return form	`24Q`, `26Q`, `27Q`

Query Parameter

Param	Type	Description	Example
financial_year	`string`	Pattern : FY[0-9]{1,4}-[0-9]{1,2}	FY 2022-23
quarter	`enum`	Quarter. Possible values: `Q1`, `Q2`, `Q3`, `Q4`	`Q3`
previous_rrr_number	`string`	Pattern : [0-9]{15}
filing_type	`enum`	TDS Return Filling type. Possible Values: `Original` `Revised`	`Original`

Payload

📘
PUT Request on Presigned URL
Once the job is successfully created, upload the payload using HTTP PUT method on generated presigned url. Read More

Follow the below guidelines to pass the payer, responsible person, payee, challan & payment in raw_body in form of a sheet structure. Refer to the Sample payload here.

Payer

Param	Type	Required	Validation	Description
name	`string`	Yes	Max Length : 75	Name of the Payer
tan	`string`	Yes	Pattern : [A-Z]{4}[0-9]{5}[A-Z]{1}	TAN of the Payer
pan	`string`	Yes	Pattern : [A-Z]{3}[PCFTGHLABJ]{1}[A-Z]{1}[0-9]{4}[A-Z]{1}	PAN of the Payer
gstin	`string`	No	Pattern : [0-9]{2}[a-zA-Z]{5}[0-9]{4}[a-zA-Z]{1}[1-9A-Za-z]{1}[CZ]{1}[0-9a-zA-Z]{1}$\|^[0-9]{4}[a-zA-Z]{3}[0-9]{5}[uUnN]{2}[0-9a-zA-Z]{1}	GSTIN of the Payer
branch	`string`	No	Max Length : 75	Branch details of the Payer if multiple locations.
street	`string`	Yes	Max Length : 25	Name of premise
area	`string`	Yes	Max Length : 25	Area of location
city	`string`	Yes	Max Length : 25	City of location
state	`enum`	Yes	Annexure - 1	State of location
postal_code	`number`	Yes	Pattern : [0-9]{6}	Pincode of location
email	`string`	Yes	Max Length : 75	Primary email for contact
mobile	`number`	Yes	Pattern: [1-9]{1}[0-9]{9}	Primary mobile number for contact

Responsible Person

Param	Type	Required	Validation	Description
designation	`string`	Yes	Max Length : 20	Designation of the responsible person
name	`string`	Yes	Max Length : 75	Name of the responsible person
pan	`string`	Yes	Pattern : [A-Z]{3}[PCFTGHLABJ]{1}[A-Z]{1}[0-9]{4}[A-Z]{1}	PAN of the responsible person
street	`string`	Yes	Max Length : 25	Name of the premise
area	`string`	Yes	Max Length : 25	Area of the location
city	`string`	Yes	Max Length : 25	City of location
state	`enum`	Yes	Annexure - 1	State of location
postal_code	`number`	Yes	Pattern : [0-9]{6}	Pincode of location
email	`string`	Yes	Max Length : 75	Primary email for contact
mobile	`number`	Yes	Pattern: [1-9]{1}[0-9]{9}	Primary mobile number for contact

Payee

Param	Type	Required	Validation	Description
sr_no	`number`	Yes		Serial Number
pan	`string`	Yes	Pattern : [A-Z]{3}[PCFTGHLABXYZ]{1}[A-Z]{1}[0-9]{4}[A-Z]{1}	PAN of the Payee. If payee doesn't have PAN then possible values are `PANNOTAVBL`,`PANAPPLIED`, `PANINVALID`, `PANNOTREQD`
name	`string`	Yes	Max Length : 75	Name of the Payee
tax_identification _number	`string`	Form 27Q - Yes	Max Length : 25	Tax Identification Number of Payee's jurisdication
street	`string`	Form 27Q - Yes	Max Length : 25	Name of premise of location
area	`string`	Form 27Q - Yes	Max Length : 25	Area of location
city	`string`	Form 27Q - Yes	Max Length : 25	City of location
state	`string`	Form 27Q - Yes	Max Length : 25	State of location
postal_code	`string`	Form 27Q - Yes	Max Length : 8	Pincode of location
country	`enum`	Form 27Q - Yes	Annexure - 4	Country of residance
email	`string`	Form 27Q - Yes	Max Length : 75	Primary email for contact
isd_code	`number`	Form 27Q - Yes	Max Length : 5	ISD code of country
mobile	`number`	Form 27Q - Yes	Pattern : [0-9]{10}	Primary mobile number for contact

Challan

Param	Type	Required	Validation	Description
challan_serial	`string`	Yes	Pattern : [0-9]{5}	Bank Challan No
bsr_code	`string`	Yes	Pattern : [0-9]{7}	Bank-Branch Code/ Form 24G Receipt Number
paid_date	`number`	Yes		Timestamp of challan paid on date
minor_head	`enum`	Yes	Annexure - 5	Minor Head of challan
tds_amount	`number`	Yes	Length : 15,2	Income Tax
surcharge	`number`	Yes	Length : 15,2	Surcharge on Income Tax
education_cess	`number`	Yes	Length : 15,2	Education cess on Income Tax
interest	`number`	Yes	Length : 15,2	Interest levied upon late deduction
late_filing_fees	`number`	Yes	Length : 15,2	Penalty levied upon late filing
other_penalty	`number`	Yes	Length : 15,2	Any Other Penalty

Payment

Param	Type	Required	Validation	Description
payee_sr_no	`number`	Yes		Payee Serial Number
challan_serial	`string`	Yes	Pattern : [0-9]{5}	Bank Challan No
bsr_code	`string`	Yes	Pattern : [0-9]{7}	Bank-Branch Code/ Form 24G Receipt Number
section	`enum`	Yes	Annexure -2	TDS section of deduction
credit_amount	`number`	Yes	Length : 15,2	Payment amount
credit_date	`number`	Yes		Time of Payment date
tds_amount	`number`	Yes	Length : 15,2	Tax amount of deduction
surcharge	`number`	Yes	Length : 15,2	Surcharge on Tax amount
education_cess	`number`	Yes	Length : 15,2	Eduction of Tax amount
deduction_date	`number`	Yes		Timestamp of Deduction date
reason_for_lower_deduction	`enum`	No	Annexure -3	Reason for non-deduction / lower deduction/ higher deduction/threshold
certificate_number	`string`	No	Max Length : 10	Certificate number issued by the Assessing Officer u/s 197 for non-deduction/lower deduction.

📘
Note : All the amount should be within 2 decimal places

Annexure

Annexure - 1 State

State Name	State Code
ANDAMAN AND NICOBAR ISLANDS	1
ANDHRA PRADESH	2
ARUNACHAL PRADESH	3
ASSAM	4
BIHAR	5
CHANDIGARH	6
DADRA & NAGAR HAVELI AND DAMAN & DIU	7
DELHI	9
GOA	10
GUJARAT	11
HARYANA	12
HIMACHAL PRADESH	13
JAMMU & KASHMIR	14
KARNATAKA	15
KERALA	16
LAKSHWADEEP	17
MADHYA PRADESH	18
MAHARASHTRA	19
MANIPUR	20
MEGHALAYA	21
MIZORAM	22
NAGALAND	23
ODISHA	24
PONDICHERRY	25
PUNJAB	26
RAJASTHAN	27
SIKKIM	28
TAMIL NADU	29
TRIPURA	30
UTTAR PRADESH	31
WEST BENGAL	32
CHHATTISGARH	33
UTTARAKHAND	34
JHARKHAND	35
TELANGANA	36
LADAKH	37

Annexure-2 Section

Section	Code
193 - Interest on Securities	193
194 - Dividend	194
194A - Other interest	94A
194B - Lotteries / Puzzle / Game	94B
194B-P - Winnings from lotteries and crossword puzzles where consideration is made in kind or cash is not sufficient to meet the tax liability and tax has been paid before such winnings are released	4BP
194BB - Winnings from Horse Race	4BB
194C - Contracts	94C
194D - Insurance	94D
194EE - NSS Deposit	4EE
194F - UTI	94F
194G - Commission on Sale of Lottery tickets	94G
194H - Commission or Brokerage	94H
194I(a) - Rent on Plant and Machinery	4IA
194I(b) - Rent on Land & Building	4IB
194J - Fees for Professional or Technical services	94J
194LA - Acquisition of certain immovable properties	94L
194LBA - Certain incomes from Units of Business Trust	4BA
194DA - Payment in respect of life insurance policy	4DA
192A - Payment of accumulated balance of provident fund, taxable in the hands of the employee	2AA
194LBB - Investment fund paying an income to a unit holder	LBB
194IA - TDS on sale of property	9IA
194LBC - Income in respect of investment in securitization trust	LBC
194IC - Payment under specified agreement	4IC
194N - Payment of certain amount in cash	94N
194K - Income from mutual fund units	94K
194J(a) - Fees for technical services, royalty for sale, distribution or exhibition of cinematographic films and call centre	4JA
194J(b) - Fee for professional service or royalty	4JB
194LBA(a) - Certain income in the form of interest from units of a business trust to a residential unit holder	BA1
194LBA(b) - Certain income in the form of dividend from units of a business trust to a resident unit holder	BA2
194NF - Payment of certain amounts in cash to non-filers	4NF
194O - TDS on E-commerce transactions	94O
192 - Payment to Government Employees other than Union Government Employees	92A
192 - Payment to Employees other than Government Employees	92B
192 - Payments made to Union Government Employees	92C
Lower deduction on account of certificate under section 197	A
No deduction on account of certificate under section 197	B
Deduction of tax at higher rate due to non-availability of PAN	C
194E - Payments to non-resident Sportsmen/Sport Associations	94E
195 - Other sums payable to Non-Residents	195
196A - Income in respect of Units of Non-Residents	96A
196B - Payments in respect of Units to an Offshore Fund	96B
196C - Income from Foreign Currency Bonds or Shares of Indian Company Payable to Non-Resident	96C
196D - Income of Foreign institutional investors from securities	96D
194LB - Income by way of interest from Infrastructure Debt fund	4LB
194LC - Income by way of interest from Indian company engaged in certain Business	4LC
194LD - Income by way of interest on certain bonds and Government Securities	4LD
194LBA(c) - Income referred to in section 10 (23FCA) from units of a business trust	BA3
194Q - Payment of certain sums for purchase of goods	94Q
194S - Payment of consideration for transfer of virtual digital asset by persons other than specified persons	94S
194SP - Payment for transfer of virtual digital asset where payment is in kind or in exchange of another virtual digital asset and tax required to be deducted is paid before such payment is released	4SP
194R - Benefits or perquisites of business or profession	94R
194RP - Benefits or perquisites of business or profession where such benefit is provided in kind or where part in cash is not sufficient to meet tax liability and tax required to be deducted is paid before such benefit is released	4RP
194P - Deduction of tax in case of specified senior citizens	94P

Annexure-3 Reason for non-deduction / lower deduction/ higher deduction/threshold

Reason	Code
Lower Deduction/No Deduction on account of Certificate u/s 197	A
No Deduction on account of Certificate u/s 197A	B
Deduction of Tax at higher rate due to Non availability of PAN	C
In case of Transporter transaction and valid PAN is provided	T
Software acquired u/s 194J	S
Transaction where Tax not been deducted as amount paid to vendor/party has not exceeded the thrashold limit	Y
No Deduction on account of payment u/s 197A (1F)	Z
Software acquired u/s 195	S
No Deduction upto Rs. 50,000 in respect of interest income from deposits held by Senior Citizen u/s 80TTB for section 194A	R
No deduction on account of payment made to person referred to in clause (iii) or clause (iv) or on account of notification issued under clause (v) for section 194N	N
No deduction or lower deduction on account of payment made to a persion or class of person on account of notification issued under sub-section (5) for section 194A	D
No deduction as per the provisions of sub-section (2A) of section 194LBA	O
No deduction or lower deduction on account of notification issued under second provision to section 194N	M
No deduction on account of payment being made to a person referred to in board circular no. 3 of 2002 dated 28th june, 2002	E
No deduction on account of payment being made to a person referred to in board circular no. 11 of 2002 dated 22nd november, 2002	E
No deduction on account of payment being made to a person referred to in board circular no. 18 of 2017 dated 28th may, 2017	E

Annexure - 4 Country

Country	Country code
AFGHANISTAN	01
AKROTIRI	02
ALBANIA	03
ALGERIA	04
AMERICAN SAMOA	05
ANDORRA	06
ANGOLA	07
ANGUILLA	08
ANTARCTICA	09
ANTIGUA AND BARBUDA	10
ARGENTINA	11
ARMENIA	12
ARUBA	13
ASHMORE AND CARTIER ISLANDS	14
AUSTRALIA	15
AUSTRIA	16
AZERBAIJAN	17
BAHRAIN	18
BAILIWICK OF GUERNSEY	19
BAILIWICK OF JERSEY	20
BAKER ISLAND	21
BANGLADESH	22
BARBADOS	23
BELARUS	24
BELGIUM	25
BELIZE	26
BENIN PORTO	27
BERMUDA	28
BHUTAN	29
BOLIVIA	30
BOSNIAAND HERZEGOVINA	31
BOTSWANA	32
BOUVET ISLAND	33
BRAZIL	34
BRITISH INDIAN OCEAN TERRITORY	35
BRUNEI	36
BULGARIA	37
BURKINA FASO	38
BURUNDI	39
CAMBODIA	40
CAMEROON	41
CANADA	42
CAPE VERDE	43
CAYMAN ISLANDS	44
CENTRAL AFRICAN REPUBLIC	45
CHAD	46
CHILE	47
CHINA	48
CHRISTMAS ISLAND	49
CLIPPERTON ISLAND	50
COCOS (KEELING) ISLANDS	51
COLOMBIA	52
COMMONWEALTH OF PUERTO RICO	53
COMMONWEALTH OF THE NORTHERN MARIANA ISLANDS	54
COMOROS	55
CONGO,DEMOCRATIC REPUBLIC OF THE	56
CONGO,REPUBLIC OF THE	57
COOK ISLANDS	58
CORAL SEA ISLANDS	59
CORAL SEA ISLANDS TERRITORY	60
COSTA RICA	61
COTE D'IVOIRE	62
CROATIA	63
CUBA	64
CYPRUS	65
CZECH REPUBLIC	66
DENMARK	67
DEPARTMENTAL COLLECTIVITY OF MAYOTTE	68
DHEKELIA	69
DJIBOUTI	70
DOMINICA	71
DOMINICAN REPUBLIC	72
EAST TIMOR (TIMORLASTE)	73
ECUADOR	74
EGYPT	75
ELSALVADOR	76
EQUATORIAL GUINEA	77
ERITREA	78
ESTONIA	79
ETHIOPIA	80
FALKLAND ISLANDS (ISLAS MALVINAS)	81
FAROE ISLANDS	82
FIJI	83
FINLAND	84
FRANCE	85
FRENCH GUIANA	86
FRENCH POLYNESIA	87
FRENCH SOUTHERN ISLANDS	88
GABON	89
GEORGIA	90
GERMANY	91
GEURNSEY	92
GHANA	93
GIBRALTAR	94
GREECE	95
GREENLAND	96
GRENADA	97
GUADELOUPE	98
GUAM	100
GUATEMALA	101
GUERNSEY	102
GUINEA	103
GUINEABISSAU	104
GUYANA	105
HAITI	106
HEARD ISLAND AND MCDONALD ISLANDS	107
HONDURAS	108
HONG KONG	109
HOWLAND ISLAND	110
HUNGARY	111
ICELAND	112
INDIA	113
INDONESIA	114
IRAN	115
IRAQ	116
IRELAND	117
ISLE OF MAN	118
ISRAEL	119
ITALY	120
JAMAICA	121
JAN MAYEN	122
JAPAN	123
JARVIS ISLAND	124
JERSEY	125
JOHNSTON ATOLL	126
JORDAN	127
KAZAKHSTAN	128
KENYA	129
KINGMAN REEF	130
KIRIBATI	131
KOREA, NORTH	132
KOREA, SOUTH	133
KOSOVO	134
KUWAIT	135
KYRGYZSTAN	136
LAOS	137
LATVIA	138
LEBANON	139
LESOTHO	140
LIBERIA	141
LIBYA	142
LIECHTENSTEIN	143
LITHUANIA	144
LUXEMBOURG	145
MACAU	146
MACEDONIA	147
MADAGASCAR	148
MALAWI	149
MALAYSIA	150
MALAYSIA (LABUAN)	151
MALDIVES	152
MALI	153
MALTA	154
MARSHALLISLANDS	155
MARTINIQUE	156
MAURITANIA	157
MAURITIUS	158
MAYOTTE	159
UNITED MEXICAN STATES	160
MICRONESIA, FEDERATED STATES OF	161
MIDWAY ISLANDS	162
MOLDOVA	163
MONACO	164
MONGOLIA	165
MONTENEGRO	166
MONTSERRAT	167
MOROCCO	168
MOZAMBIQUE	169
MYANMAR (BURMA)	170
NAMIBIA	171
NAURU	172
NAVASSA ISLAND	173
NEPAL	174
NETHERLANDS	175
NETHERLANDS ANTILLES	176
NEW CALEDONIA	177
NEWZEALAND	178
NICARAGUA	179
NIGER	180
NIGERIA	181
NIUE	182
NORFOLK ISLAND	183
NORTHERN MARIANA ISLANDS	184
NORWAY	185
OMAN	186
PAKISTAN	187
PALAU	188
PALMYRA ATOLL	189
PANAMA	190
PAPUA NEW GUINEA	191
PARACEL ISLANDS	192
PARAGUAY	193
PERU	194
PHILIPPINES	195
PITCAIRN ISLANDS	196
PITCAIRN, HENDERSON, DUCIE, AND OENO ISLANDS	197
POLAND	198
PORTUGAL	199
PUERTO RICO	200
QATAR	201
REUNION	202
ROMANIA	203
RUSSIA	204
RWANDA	205
SAINT BARTHELEMY	206
SAINT HELENA	207
SAINT KITTS AND NEVIS	208
SAINT LUCIA	209
SAINT MARTIN	210
SAINT PIERRE AND MIQUELON	211
SAINT VINCENT AND THE GRENADINES	212
SAMOA	213
SANMARINO	214
SAO TOME AND PRINCIPE	215
SAUDI ARABIA	216
SENEGAL	217
SERBIA	218
SEYCHELLES	219
SIERRA LEONE	220
SINGAPORE	221
SLOVAKIA	222
SLOVENIA	223
SOLOMON ISLANDS	224
SOMALIA	225
SOUTH AFRICA	226
SOUTH GEORGIA AND SOUTH SANDWICH ISLANDS	227
SPRATLY ISLANDS	228
SPAIN	229
SRI LANKA	230
ST. VINCENT & GRENADINES	231
SUDAN	232
SURINAME	233
SVALBARD	234
SWAZILAND	235
SWEDEN	236
SWITZERLAND	237
SYRIA	238
TAIWAN	239
TAJIKISTAN	240
TANZANIA	241
TERRITORIAL COLLECTIVITY OF ST. PIERRE & MIQUELON	242
TERRITORY OF AMERICAN SAMOA	243
TERRITORY OF ASHMORE AND CARTIER ISLANDS	244
TERRITORY OF CHRISTMAS ISLAND	245
TERRITORY OF COCOS (KEELING) ISLANDS	246
TERRITORY OF GUAM	247
TERRITORY OF HEARD ISLAND & MCDONALD ISLANDS	248
TERRITORY OF NORFOLK ISLAND	249
THAILAND	250
THE BAHAMAS	251
THE GAMBIA	252
TOGO	253
TOKELAU	254
TONGA	255
TRINIDAD AND TOBAGO	256
TUNISIA	257
TURKEY	258
TURKMENISTAN	259
TURKS AND CAICOS ISLANDS	260
TUVALU	261
UGANDA	262
UKRAINE	263
UNITED ARAB EMIRATES	264
UNITED KINGDOM	265
UNITED STATES VIRGIN ISLANDS	266
UNITED STATES OF AMERICA	267
URUGUAY	268
UZBEKISTAN	269
VANUATU	270
VATICAN CITY (HOLYSEE)	271
VENEZUELA	272
VIETNAM	273
VIRGIN ISLANDS, BRITISH	274
VIRGIN ISLANDS, U.S.	275
WAKE ISLAND	276
WALLIS AND FUTUNA	277
WESTERN SAHARA	278
YEMEN	279
ZAMBIA	280
ZIMBABWE	281
COMBODIA	282
CONGO	283
IVORY COAST	284
WEST INDIES	285
BRITISH VIRGIN ISLANDS	286

Annexure -5 Minor Head

Minor Head	Code
(200) TDS Payable by Tax Payer	200
(400) TDS Regular Assessment (Raised by I.T. Dept.)	400
(100) Advance Tax	100

Response

Param	Type	Description
code	`number`	HTTP response status code
transaction_id	`string`	Unique Transaction id to track the request
timestamp	`number`	Timestamp of the request
status	`enum`	Possbile values are : JOBDONE, JOBQUEUED, JOBDONE
signed_url	`string`	JOBDONE : signed url of txt file JOBFAILED : signed url of validation report

Response Caching

Response caching is not available for this API. Learn more about our response caching mechanism here

Wallet Charges

Since Prepare TDS Return API is a Paid API, a wallet charge will take place.

Versioning

This API is currently in major version 1.0. Refer to our versioning policies here

Prepare TDS Return

Overview

Problem

Solution

Endpoint

Request

Path Parameter

Query Parameter

Payload

📘
PUT Request on Presigned URL

Payer

Responsible Person

Payee

Challan

Payment

📘
Note : All the amount should be within 2 decimal places

Annexure

Annexure - 1 State

Annexure-2 Section

Annexure-3 Reason for non-deduction / lower deduction/ higher deduction/threshold

Annexure - 4 Country

Annexure -5 Minor Head

Response

Response Caching

Wallet Charges

Versioning

Overview

Problem

Solution

Endpoint

Request

Path Parameter

Query Parameter

Payload

📘PUT Request on Presigned URL

Payer

Responsible Person

Payee

Challan

Payment

📘Note : All the amount should be within 2 decimal places

Annexure

Annexure - 1 State

Annexure-2 Section

Annexure-3 Reason for non-deduction / lower deduction/ higher deduction/threshold

Annexure - 4 Country

Annexure -5 Minor Head

Response

Response Caching

Wallet Charges

Versioning

📘
PUT Request on Presigned URL

📘
Note : All the amount should be within 2 decimal places