CPC TDS API — Overview, Authentication & Authorization

Consolidated reference for API-based TDS/TCS statement filing and enablement APIs, including authentication, request/response formats, and form-wise endpoints.

Table of Contents

Introduction
API Overview
Authentication & Authorization
Workflow for Government & Non-Government TSPs

Introduction

API-based TDS/TCS statement filing enables integration with TRACES to automate workflows for Forms 24Q, 26Q, 27Q, and 27EQ.

1.1 API Classifications

Statement Filing APIs — create, update, fetch, validate, track statements for 24Q/26Q/27Q/27EQ.
Enablement APIs — create sandbox test data for AIN, PAN, TAN, LDC/NDC; perform AIN/TAN validations.

1.2 Key Benefits

Process Automation: end‑to‑end workflow, pre‑validation, faster reconciliation.
Reduced Desktop Dependencies: no RPU/FVU; programmatic schemas; fewer versioning issues.
Accuracy & Compliance: schema checks, PAN/AIN/TAN validation, challan matching.
Enterprise Scalability: bulk/multi‑entity filings for large deductors/TSPs.

2. API Overview

APIs are stateless REST over HTTPS. The following standardizes URIs, versioning, headers, and payloads.

2.1 URI Pattern

https://test-api.tdscpc.gov.in/ext/forms/{formNumber}/{apiVersion}/{finYear}/{quarter}/{entity}

Element	Description	Example
HTTPS	All APIs over HTTPS (HTTP in non‑prod only).	https://…
formNumber	Statement form number.	24Q \| 26Q \| 27Q \| 27EQ
apiVersion	Lowercase, prefixed with `v`.	v1.0
finYear	Start year of FY.	For FY 2025–26 use 2025
quarter	Quarter of FY.	1=Apr–Jun, 2=Jul–Sep, 3=Oct–Dec, 4=Jan–Mar
entity	Lowercase resource noun.	header \| challans \| deductees \| collectees

2.2 Request Payloads

GET (multiple records): ?param1={value1}&param2={value2}&…

POST/PUT: Content-Type: application/json

Authentication & Authorization

OAuth 2.0 enforced: Authorization Code + PKCE for user flows; Client Credentials for M2M

3.1 Authorization Code Flow with PKCE

PKCE (Proof Key for Code Exchange) is recommended for public clients that cannot securely store a client secret. It mitigates code interception, replay, app impersonation, and redirect hijacking. The flow issues an access token (and a refresh token) after user authentication and consent. pkceflow

Step 1 — Generate PKCE

code_verifier  = <high-entropy random string>
code_challenge = BASE64URL(SHA256(code_verifier))

Step 2 — Authorization Request

GET https://test-auth.tdscpc.gov.in/auth?response_type=code&client_id=XXXXXXXX&redirect_uri=https://test-dev.tdscpc.gov.in/oauth2-redirect.html&state=U2F0IEZlYiAxNCAyMDI2&code_challenge=SiyHugtRXSQRVBjf8caviK9dFwcZ5jBXLVTJSv2mAuk&code_challenge_method=S256

Step 3 — User Authentication & Consent

User logs in and approves permissions.

Step 4 — Authorization Code Redirect

https://test-dev.tdscpc.gov.in/oauth2-redirect.html?code=<AUTHORIZATION_CODE>

Step 5 — Token Request

POST https://test-auth.tdscpc.gov.in/token
Content-Type: application/x-www-form-urlencoded

Reques
{
  "grant_type":"authorization_code"
  "code":"972427d2-0bbc-4963-9903-d7c8ff96e0cb"
  "client_id":"XXXXXXXXX".
  "redirect_uri":"https://test-dev.tdscpc.gov.in/oauth2-redirect.html"
  "code_verifier":"S5YmlY_kNFZJ9OdioumFihFJvUXwPkTdT1hGpJd9LGA";
}

 Response
{
    "access_token": "6Mil0ujQ",
    "expires_in": 900,
    "refresh_expires_in": 1800,
    "refresh_token": "Jdapy8nJlrLNrUw",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "97f63a56-9826-45ca-b146-35bdabc54c48",
    "scope": "email profile"
}

Access Token Renewal (Refresh Token)

POST https://test-auth.tdscpc.gov.in/token
Content-Type: application/x-www-form-urlencoded

"grant_type":"refresh_token";
"client_id":"XXXXXXXXXXXXXX"'
"refresh_token":"XXXXXXXXXXXXXXXXXXXXXX"

3.2 Client Credentials Flow

Intended for machine-to-machine communication by confidential clients that can securely store a client secret. No end-user is involved, and refresh tokens are not issued (request a new access token when needed).

Core Characteristics

No User Interaction:

There are no login screens or consent forms because no "user" is involved.

Confidential Clients Only:

Only applications that can securely store a secret (e.g., backend servers) should use this flow.

No Refresh Tokens:

refresh tokens are not issued. Since the client is a trusted machine with stored credentials, it can simply request a new access token whenever the old one expires. The process involves only two main steps between the client and the authorization server: The portal will request an OAuth2 token from the Authorization Server.
ClientCredentailsFlow

Step 1 — Token Request

POST https://test-auth.tdscpc.gov.in/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id=<CLIENT_ID>
client_secret=<CLIENT_SECRET>
scope=<SCOPE (optional)>

Step 2 — Token Response

 {
  "access_token": "",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": ""
}

Use the access token to call protected resources: Authorization: Bearer

Workflow for Government & Non‑Government TSPs

3.1 Common Steps

Prepare statement data (challans + deductees).
Authenticate via OAuth 2.0 PKCE and obtain access token.
Create Header (POST /header) before challans/deductees.
Submit Challans (POST /challans bulk).
Submit Deductee Annexures (/annex1, /annex2, /annex3).
Check Status (GET /status); Validate; download errors (GET /errorFileDownload).
Submit the statement on TRACES after quarter‑end.

3.2 Additional (Government TSPs – 24G BIN)

Pre-filled Form 24G generated after validation.
PAO verifies on TRACES.
BIN generated post-approval; view via GET /challans.