ITR Submit 2FA OTP

Endpoint Overview

POST /api/v1/itr/submit-2fa

Description

The ITR Submit 2FA API completes the two-factor authentication process by validating the One-Time Password (OTP) that was sent to the taxpayer during the preceding Generate 2FA step. Upon successful OTP verification, the user is authenticated and a secure session is established, unlocking access to the taxpayer's Income Tax Return data for subsequent retrieval operations.

This endpoint is the third step in the ITR verification workflow. After initiating a session (which returns a client_id) and triggering an OTP via the Generate 2FA endpoint, you must call this endpoint with the received OTP to prove the taxpayer's identity. A successful response confirms the session is fully authenticated, allowing you to proceed with ITR data fetch calls using the same client_id. This mechanism ensures that sensitive tax filing information is only accessible to verified and authorized individuals.

Key Benefits

Secure Identity Confirmation: Validates taxpayer identity through OTP verification before granting access to sensitive ITR data

Seamless Workflow Continuity: Authenticates the session established in prior steps, enabling smooth progression to data retrieval

Fraud Prevention: Ensures only the legitimate taxpayer or authorized party can access income tax records

Regulatory Compliance: Satisfies two-factor authentication requirements mandated by Indian tax data access regulations

Use Cases

Banking & Lending

Fintech & Wealth Management

Insurance & NBFC

Complete borrower identity verification before retrieving ITR data for loan underwriting and credit assessment

Authenticate taxpayers during digital loan origination workflows to access income proof in real time

Validate applicant identity for pre-approved loan offers based on verified tax filing history

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for API authentication. Format: `Bearer <JWT_TOKEN>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
client_id	string	Yes	Unique session identifier obtained from the initial ITR verification request. This ties the OTP submission to the correct taxpayer session.
otp	string	Yes	The One-Time Password received by the taxpayer via SMS, triggered by the Generate 2FA endpoint.

Example Request

{
  "client_id": "itr_GphpGlzxZ0ficAventBk",
  "otp": "156519"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains the authentication result
data.logged_in	boolean	Indicates whether the OTP was verified and the session is now fully authenticated (`true` for success)
status_code	integer	HTTP status code of the response (200 for success)
message_code	string	Machine-readable status code (e.g., `"success"`)
message	string	Human-readable message describing the result
success	boolean	Indicates if the API request was processed successfully

Example Successful Response

{
  "data": {
    "logged_in": true
  },
  "status_code": 200,
  "message_code": "success",
  "message": "Logged In Successfully",
  "success": true
}

Possible Error Responses

Invalid OTP

Expired OTP

Invalid Client ID

Authentication Error

Server Error

{
  "data": null,
  "status_code": 422,
  "message_code": "invalid_otp",
  "message": "The OTP entered is invalid. Please check and try again.",
  "success": false
}

This error occurs when the submitted OTP does not match the one sent to the taxpayer. Verify the OTP value and ensure it has not expired before resubmitting.

Integration Best Practices

Security Recommendations

Secure OTP Handling: Never log, cache, or persist OTP values in your system. Process the OTP in memory and discard it immediately after submission.

Token Protection: Store JWT tokens securely on the server side. Never expose them in client-side code, browser storage, or version control systems.

HTTPS Only: Always use HTTPS endpoints to ensure OTP values and authentication tokens are encrypted during transmission.

Session Integrity: Validate that the client_id is associated with the current user session to prevent cross-session OTP submission attacks.

Rate Limiting: Implement rate limiting on OTP submission attempts to mitigate brute-force attacks on OTP values.

Audit Trail: Maintain logs of 2FA verification attempts (without recording the OTP itself) for security monitoring and compliance purposes.

User Experience Guidelines

Clear OTP Input: Provide a dedicated, auto-focused input field for OTP entry with the correct input length clearly indicated.

Countdown Timer: Display a visible countdown timer showing OTP validity duration so users know how much time remains.

Resend Option: Offer a "Resend OTP" option that calls the Generate 2FA endpoint again, with an appropriate cooldown period to prevent spam.

Error Messaging: Show specific, actionable error messages — distinguish between invalid OTP, expired OTP, and session errors so users know exactly what to do.

Auto-Submit: Consider auto-submitting the OTP once the user has entered the required number of digits for a smoother experience.

Loading State: Display a loading indicator during the API call to signal that verification is in progress and prevent duplicate submissions.

Code Samples

cURL

Python

Node.js

Related APIs

ITR Initialization API: Initiates the ITR verification session by accepting the taxpayer's PAN and returns a client_id required for subsequent steps.

ITR Generate 2FA API: Triggers the OTP delivery to the taxpayer's registered contact, which is required before calling this Submit 2FA endpoint.

ITR Fetch Data API: Retrieves the taxpayer's Income Tax Return data after successful 2FA authentication using the authenticated client_id.

PAN Verification API: Validates PAN card details independently, often used alongside ITR workflows for identity confirmation.

Compliance and Legal Considerations

Ensure that all ITR data access is performed with explicit consent from the taxpayer. The two-factor authentication mechanism is mandated to protect sensitive financial information and must not be bypassed or circumvented. All OTP values must be handled in compliance with data protection regulations and should never be stored, logged, or transmitted in plain text beyond the immediate verification call. Organizations must adhere to applicable Indian data privacy laws, including the Digital Personal Data Protection Act (DPDPA), and maintain appropriate data processing agreements. Implement data minimization practices — only collect and retain ITR data that is strictly necessary for the stated business purpose. Maintain comprehensive audit logs of all 2FA verification attempts and ITR data access events for regulatory compliance and dispute resolution.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/itr/submit-2fa' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "itr_GphpGlzxZ0ficAventBk", "otp": "156119" }'

Submit 2FA

ITR Submit 2FA OTP#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses