Generate OTP for GSTIN Verification

Endpoint Overview

POST /api/v1/corporate-otp/gstin/generate-otp

Description

This API endpoint generates a One-Time Password (OTP) for GSTIN (Goods and Services Tax Identification Number) verification. It sends the OTP to the registered mobile number associated with the GSTIN. This endpoint is part of the corporate OTP verification flow that enables secure authentication before accessing GST-related information.

Key Benefits

Secure verification process for accessing GST data

Simple integration with minimal required parameters

Real-time OTP delivery to registered mobile numbers

Supports compliance with GST verification requirements

Use Cases

Financial Services

E-commerce

Business Services

Verify business identity during loan application processing

Validate GST registration status before extending credit

Authenticate business clients during onboarding

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.io

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication (JWT)
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
type	String	Yes	OTP type: `email`, `mobile`, `both`
client_id	String	Yes	Client ID of the client
otp_length	Integer	No	Length of the OTP
sms_otp_template	String	No	SMS OTP template identifier
email_otp_template	String	No	Email OTP template identifier
otp_expiry	Integer	No	OTP Expiry duration (in minutes)

Example Request

{
    "client_id": "gst_otp_vRvefXGKgTutAfhcSEPo",
    "type": "mobile"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.otp_sent	Boolean	Indicates if OTP was successfully sent (true/false)
status_code	Integer	HTTP status code of the response
message_code	String	Short code indicating the result status
message	String	Human-readable message describing the result
success	Boolean	Overall success status of the request

Example Successful Response

{
    "data": {
        "otp_sent": true
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Success",
    "success": true
}

Possible Error Responses

Invalid Client ID

OTP Limit Exceeded

Authentication Error

{
    "data": null,
    "status_code": 400,
    "message_code": "invalid_client_id",
    "message": "The provided client ID is invalid or not found",
    "success": false
}

This error occurs when the client_id provided in the request is not valid or not registered in the system.

Integration Best Practices

Security Recommendations

Store API keys securely and never expose them in client-side code

Implement proper error handling to manage failed OTP generation attempts

Use HTTPS for all API communications to ensure data security

Implement rate limiting on your side to prevent excessive OTP generation attempts

User Experience Guidelines

Clearly inform users that an OTP will be sent to their registered mobile number

Provide clear instructions on where to enter the OTP once received

Implement a resend OTP option with appropriate cooldown periods

Display appropriate error messages when OTP generation fails

Code Samples

cURL

Python

Node.js

Related APIs

GSTIN Verification with OTP: Used to verify a GSTIN using the OTP generated by this endpoint

GSTIN Details Retrieval: Fetches detailed information about a verified GSTIN

Corporate OTP Status Check: Checks the status of a previously generated OTP

Compliance and Legal Considerations

This API facilitates access to GST data which is regulated by the Goods and Services Tax Network (GSTN) in India

Ensure you have proper consent from the business entity before initiating the verification process

The data accessed should be used in compliance with applicable data protection and privacy laws

Unauthorized access or misuse of GST data may result in legal consequences

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/corporate-otp/gstin/generate-otp' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "gst_otp_vRvefXGKgTutAfhcSEPo", "type": "mobile" }'

Generate OTP

Generate OTP for GSTIN Verification#

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

Generate OTP for GSTIN Verification

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples