Skip to main content
Use Sandbox’s TDS challan API to find challans for a TAN and check their payment status, tax breakdown, and available consumption details. TRACES supports challan status searches by deposit date or challan particulars.

​
Before you start

  • Obtain a Sandbox access token using the Quickstart guide.
  • Keep the TAN and its TRACES password ready.
  • Choose the deposit date range to search. For a specific challan, keep its BSR code, deposit date, and serial number ready.
The examples use fictional challan data. Replace the sample TAN and payment details with your own values. Use the same TAN as the saved credentials.

​
Search and check TDS challans

1

Add the TRACES credentials

Add the TAN and its password with the Add TRACES credentials endpoint.
Use the same Sandbox workspace for credential setup and challan requests. Skip this step if valid credentials are already saved for the TAN. To replace saved credentials, delete the credentials, then add the new password.
2

Search by deposit date

Call Search TDS challans with the TAN and the deposit date range. This example searches July 2026.
Send deposit dates as Unix timestamps in milliseconds. The API interprets their calendar dates in Asia/Kolkata. from_date_epoch and to_date_epoch are required.Read the challans in data.data. The response includes data.totalPages and data.totalElements. To request another page, increase page_number, starting at 0. Keep the date range and page_size the same across pages. Stop when page_number reaches data.totalPages - 1. page_number and page_size are optional.A search with no matching challans returns HTTP 200 with an empty data.data list.
3

Fetch a specific challan

Call Fetch TDS challan details with the payment details from a search result or your challan record. You can skip the search when you already have these details.
Send the BSR code and challan serial number as strings to preserve leading zeros. The example deposit date is 17 July 2026 in Asia/Kolkata.Read data.status and data.tax_breakdown from the response. When data.consumption_details is present, use its claimed and available amounts to review utilization. A null value means consumption details are unavailable.

​
Resolve request errors

If a challan request returns HTTP 521 with Credentials not found, add the TRACES credentials for the TAN in your current Sandbox workspace, then retry. If a challan request returns HTTP 401 with Invalid credentials, check the TAN and TRACES password. To replace the password, delete the saved credentials, then add the correct credentials. If a challan request returns HTTP 500 with Failed to log in to TRACES, retry after some time. A specific challan lookup returns HTTP 521 with Challan not found when no challan matches the supplied details. Check the TAN, BSR code, serial number, and deposit date before retrying. See the API error guide for other errors.