Submit OTP

Submit GSTIN OTP

Endpoint Overview

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

Description
This API endpoint enables the submission of a One-Time Password (OTP) received from the GST portal to complete the GSTIN verification process. Upon successful OTP validation, the API returns comprehensive details about the business entity associated with the GSTIN, including business identification, contact information, tax registration status, business classification, and HSN codes for goods and services offered.

Key Benefits

Seamless Verification Process: Complete GST verification with minimal user interaction
Rich Business Data: Access comprehensive business details including contact information, tax status, and business classifications
HSN Code Access: Retrieve accurate HSN codes for goods and services offered by the business
Real-time Validation: Instantly validate GST registration status and business legitimacy

Use Cases

Financial Services

E-commerce

Enterprise Solutions

KYC verification for business account onboarding

Risk assessment for commercial lending

Business identity verification for payment gateways

Merchant onboarding for payment processors

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	JWT Bearer token for authentication (Format: `Bearer YOUR_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 received from the initial GSTIN verification request
otp	String	Yes	The OTP received on the registered mobile number from the GST portal

Example Request

json{
    "client_id": "gst_otp_tfwewGShXrPxKSmvyrmg",
    "otp": "1234"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains verification status and business details
data.verified	Boolean	Indicates whether the GSTIN verification was successful
data.details	Object	Contains comprehensive business information
data.details.contact_details	Object	Contains principal and additional contact information
data.details.gstin	String	The verified GSTIN number
data.details.pan_number	String	PAN number associated with the GSTIN
data.details.business_name	String	Trade name of the business
data.details.legal_name	String	Legal name of the entity
data.details.constitution_of_business	String	Legal structure of the business (e.g., Private Limited Company)
data.details.taxpayer_type	String	Type of taxpayer (e.g., Regular)
data.details.gstin_status	String	Current status of the GSTIN (e.g., Active)
data.details.date_of_registration	String	Date of GST registration (YYYY-MM-DD format)
data.details.hsn_info	Object	Contains HSN codes for goods and services
status_code	Integer	HTTP status code of the request
success	Boolean	Indicates whether the API call was successful
message	String	Response message
message_code	String	Code representing the response message

Example Successful Response

{
"data": {
    "verified": true,
    "details": {
        "contact_details": {
            "principal": {
                "address": "House No.364, Tehsil, Sikar, Rajasthan, 123456",
                "email": "advchahat121@gmail.com",
                "mobile": "8571967928",
                "nature_of_business": "Office / Sale Office"
            },
            "additional": []
        },
        "promoters": [],
        "annual_turnover": "",
        "annual_turnover_fy": "",
        "percentage_in_cash_fy": "",
        "percentage_in_cash": "",
        "aadhaar_validation": "Yes",
        "aadhaar_validation_date": "2021-07-15",
        "address_details": {},
        "liability_percentage_details": {},
        "less_info": true,
        "client_id": null,
        "gstin": "08ABBCS1234D1ZN",
        "pan_number": "ABBCS1234D",
        "business_name": "Services Private Limited",
        "legal_name": "Services Private Limited",
        "center_jurisdiction": "Commissionerate - ALWAR,Division - GST DIVISION-G SIKAR,Range",
        "state_jurisdiction": "State - Rajasthan,Zone - Jaipur-IV,Circle",
        "date_of_registration": "2021-07-15",
        "constitution_of_business": "Private Limited Company",
        "taxpayer_type": "Regular",
        "gstin_status": "Active",
        "date_of_cancellation": "1800-01-01",
        "field_visit_conducted": "No",
        "nature_bus_activities": [
            "Supplier of Services"
        ],
        "nature_of_core_business_activity_code": "SPO",
        "nature_of_core_business_activity_description": "Service Provider and Others",
        "filing_status": [],
        "address": null,
        "hsn_info": {
            "goods": [],
            "services": [
                {
                    "description": "Information technology (IT) consulting and support services",
                    "hsn": "998313"
                },
                {
                    "description": "Other support services n.e.c.",
                    "hsn": "998599"
                },
                {
                    "description": "Other information technology services n.e.c",
                    "hsn": "998319"
                },
                {
                    "description": "Support services",
                    "hsn": "9985"
                }
            ]
        },
        "filing_frequency": []
    }
},
"status_code": 200,
"success": true,
"message": "Success",
"message_code": "success"
}

Possible Error Responses

Invalid OTP

Invalid Client ID

json{
"status_code": 400,
"success": false,
"message": "Invalid OTP provided",
"message_code": "invalid_otp"
}
The OTP provided is incorrect or has expired. Request a new OTP and try again.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement proper error handling to prevent information leakage

Ensure OTP submission is performed server-side to prevent tampering

Set appropriate token expiration times to minimize security risks

User Experience Guidelines

Implement a clear OTP entry UI with validation feedback

Display a countdown timer for OTP expiration

Provide a "Resend OTP" option if the user doesn't receive it

Show a user-friendly loading state during verification

Code Samples

cURL

Python

Node.js

Related APIs

GSTIN Verification Initiation: Initiates the GSTIN verification process and requests an OTP
Business PAN Verification: Verifies business entities using their PAN details
Corporate Identity Verification: Comprehensive verification of business entities

Compliance and Legal Considerations

The GST verification data is provided by the Indian government's GST Portal and is subject to their terms of use. This data should be used in compliance with applicable privacy laws and should not be used for activities prohibited by law. Users must ensure they have proper consent for verifying GSTINs and handling the resulting data in accordance with India's data protection regulations.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/corporate-otp/gstin/submit-otp' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "gst_otp_tfwewGShXrPxKSmvyrmg", "otp": "1234" }'

{ "data": { "verified": true, "details": { "contact_details": { "principal": { "address": "House No.364, Tehsil, Sikar, Rajasthan, 123456", "email": "advchahat121@gmail.com", "mobile": "8571967928", "nature_of_business": "Office / Sale Office" }, "additional": [] }, "promoters": [], "annual_turnover": "", "annual_turnover_fy": "", "percentage_in_cash_fy": "", "percentage_in_cash": "", "aadhaar_validation": "Yes", "aadhaar_validation_date": "2021-07-15", "address_details": {}, "liability_percentage_details": {}, "less_info": true, "client_id": null, "gstin": "08ABBCS1234D1ZN", "pan_number": "ABBCS1234D", "business_name": "Services Private Limited", "legal_name": "Services Private Limited", "center_jurisdiction": "Commissionerate - ALWAR,Division - GST DIVISION-G SIKAR,Range", "state_jurisdiction": "State - Rajasthan,Zone - Jaipur-IV,Circle", "date_of_registration": "2021-07-15", "constitution_of_business": "Private Limited Company", "taxpayer_type": "Regular", "gstin_status": "Active", "date_of_cancellation": "1800-01-01", "field_visit_conducted": "No", "nature_bus_activities": [ "Supplier of Services" ], "nature_of_core_business_activity_code": "SPO", "nature_of_core_business_activity_description": "Service Provider and Others", "filing_status": [], "address": null, "hsn_info": { "goods": [], "services": [ { "description": "Information technology (IT) consulting and support services", "hsn": "998313" }, { "description": "Other support services n.e.c.", "hsn": "998599" }, { "description": "Other information technology services n.e.c", "hsn": "998319" }, { "description": "Support services", "hsn": "9985" } ] }, "filing_frequency": [] } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Request