Udyam OTP Async - Submit OTP

Endpoint Overview

POST /api/v1/udyam-otp/async/submit-otp

Description

The Udyam OTP Async - Submit OTP API allows you to submit the OTP entered by the user to complete the Udyam registration verification process. This endpoint is the third step in the async OTP verification flow — called after the OTP has been dispatched via the Send OTP endpoint and delivery has been confirmed via the Send OTP Status endpoint.

By providing the client_id (which ties the submission to the original OTP request) along with the otp entered by the user, this API triggers the asynchronous verification of the submitted code against the Udyam registration. The response returns a pending status, indicating the verification is being processed asynchronously. The final verification result is delivered either via the configured webhook or by polling the Submit OTP Status endpoint.

Key Benefits

Seamless Flow Completion: Closes the OTP verification loop by securely submitting the user-entered code against the original Udyam registration request, enabling full MSME identity verification.

Asynchronous Processing: Verification is handled asynchronously, ensuring your application remains responsive and non-blocking while the OTP is validated against Udyam records.

Stateful Session Management: The client_id ties the OTP submission to the original dispatch session, eliminating the need to re-transmit sensitive details such as the registration number or mobile number.

Webhook & Polling Support: Final verification results can be received via the configured webhook URL from the original Send OTP request, or retrieved on demand via the Submit OTP Status endpoint.

Use Cases

Fintech & Lending

Government & Compliance

B2B Marketplaces

Submit the OTP entered by MSME borrowers during loan onboarding to finalize Udyam registration verification and unlock subsequent credit assessment steps.

Integrate OTP submission into automated KYC pipelines to programmatically complete verification as part of a multi-step identity validation workflow.

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 authentication. Format: `Bearer <JWT_TOKEN>`
`Content-Type`	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
`client_id`	String	Yes	The unique client identifier returned by the Udyam OTP Async Send OTP API. Links this OTP submission to the original dispatch session.
`otp`	String	Yes	The OTP entered by the user, as received on their registered mobile number or email address.

Example Request

{
    "client_id": "udyam_otp_async_SBsIvDUxXlwhskcsAjlF",
    "otp": "305158"
}

Process Response

Response Parameters

Parameter	Type	Description
`data`	Object	Contains the result payload of the OTP submission request
`data.client_id`	String	The unique client identifier corresponding to the original OTP request session
`data.status`	String	The current processing status of the OTP submission. Returns `pending` when the submission has been accepted and verification is being processed asynchronously, `not_started` if OTP is not sent
`status_code`	Integer	HTTP status code of the response (e.g., `200` for success)
`success`	Boolean	Indicates whether the API call was successful (`true`) or not (`false`)
`message`	String	A human-readable message describing the result (e.g., `"Success"`)
`message_code`	String	A machine-readable code corresponding to the message (e.g., `"success"`)

Example Successful Response

{
    "data": {
        "client_id": "udyam_otp_async_SBsIvDUxXlwhskcsAjlF",
        "status": "pending"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Unauthorized

Invalid Request

Internal Server Error

{
    "status_code": 401,
    "success": false,
    "message": "Authentication credentials were not provided or are invalid.",
    "message_code": "unauthorized"
}

Returned when the JWT Bearer token is missing, expired, or invalid. Ensure you are using the correct token for the target environment (sandbox or production).

Integration Best Practices

Security Recommendations

Never log OTP values: The otp field contains a sensitive, time-limited code. Never write it to application logs, analytics pipelines, or error tracking tools.

Submit OTPs server-side only: Route OTP submissions through your backend to prevent exposure of both the JWT token and the OTP value in client-side code or network requests visible to the user.

Use environment-specific tokens: Always use the JWT token issued for the corresponding environment — never use a production token against the sandbox base URL or vice versa.

Protect the client_id: Treat the client_id as a session token. Avoid storing it in browser-accessible storage or including it in client-side URLs to prevent session hijacking.

User Experience Guidelines

Show a loading state after submission: Since the verification result is asynchronous and the response returns pending, display a "Verifying..." indicator immediately after the user submits the OTP to set accurate expectations.

Poll or await webhook before advancing the flow: Do not advance the user to a success screen based solely on the pending response. Wait for the final verification result from the Submit OTP Status endpoint or your configured webhook before confirming success or failure.

Handle incorrect OTP gracefully: If the final status indicates OTP mismatch or expiry, surface a clear message such as "Incorrect or expired OTP" and offer the user the option to resend rather than re-submitting the same code.

Set OTP input constraints: Enforce input validation on the OTP field in your UI (e.g., numeric only, fixed length) to reduce submission errors caused by accidental character inclusions.

Code Samples

cURL

Python

Node.js

Related APIs

Udyam OTP Async - Send OTP: Initiates the asynchronous OTP dispatch to the Udyam-registered entity's mobile or email. Provides the client_id required by this Submit OTP endpoint.

Udyam OTP Async - Send OTP Status: Checks the delivery status of the OTP dispatch (otp_sent, pending, or failed). Should be confirmed as otp_sent before calling this Submit OTP endpoint.

Udyam OTP Async - Submit OTP Status: Retrieves the final verification result of the submitted OTP. Call this endpoint after receiving a pending response from Submit OTP to determine whether the Udyam registration was successfully verified.

Compliance and Legal Considerations

OTP Sensitivity: OTPs are time-limited credentials used to establish user consent. They must never be stored, logged, or transmitted outside of the immediate verification flow. Treat them with the same sensitivity as passwords.

User Consent: Submitting an OTP on behalf of a user constitutes an action that records their consent to Udyam registration verification. Ensure the user has explicitly entered and authorized the OTP submission within your interface.

Data Protection: The client_id and otp values must be transmitted exclusively over HTTPS. Ensure your infrastructure complies with India's Digital Personal Data Protection Act (DPDPA) with respect to the handling of authentication data tied to MSME business identities.

Audit Trail: Log the client_id and submission timestamp (without the OTP value) as part of your KYC audit records to demonstrate that verification was completed via proper consent-driven OTP submission.

Regulatory Alignment: Usage of this API within MSME verification workflows should align with the MSME Development Act and any directives from the Ministry of MSME, Government of India.

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/udyam-otp/async/submit-otp' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "udyam_otp_async_bgKqddCbbfhmJGqouVIK" }'

{ "data": { "client_id": "udyam_otp_async_bgKqddCbbfhmJGqouVIK", "status": "pending" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Submit OTP

Udyam OTP Async - Submit 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