Submit OTP

Endpoint Overview

POST /api/v1/sms/submit-otp

Description

This endpoint allows clients to submit and verify a One-Time Password (OTP) that was previously sent to a user's mobile number. It completes the SMS verification flow by validating the OTP entered by the user against the one generated by the system. Upon successful verification, the API confirms the authenticity of the user's mobile number.

Key Benefits

Completes the two-factor authentication process for enhanced security

Verifies user's mobile number ownership with minimal friction

Provides immediate verification status feedback

Supports regulatory compliance for identity verification requirements

Use Cases

Financial Services

E-commerce

Healthcare

User verification during account registration or login

Secure transaction authorization for payments

KYC compliance during customer 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 authentication using JWT
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Client ID received from the previous OTP generation step
otp	String	Yes	The 6-digit OTP code received by the user

Example Request

{
    "client_id": "send_sms_otp_xYrDQJCymqltgNgbmTfT",
    "otp": "123456"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains verification details
data.client_id	String	Unique client ID for this verification session
data.mobile	String	Mobile number that received the OTP
data.otp_sent	Boolean	Indicates if OTP was successfully sent
data.otp_verified	Boolean	Indicates if OTP was successfully verified
status_code	Integer	HTTP status code
success	Boolean	Overall success status of the request
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "send_sms_otp_xYrDQJCymqltgNgbmTfT",
        "mobile": "7042174106",
        "otp_sent": true,
        "otp_verified": true
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Invalid OTP

OTP Expired

Max Attempts Exceeded

Server Error

{
    "data": null,
    "status_code": 404,
    "message": "Invalid Client ID.",
    "message_code": null,
    "success": false,
}

This error occurs when the UPI verification service is temporarily unavailable.

Integration Best Practices

Security Recommendations

Implement rate limiting to prevent brute force attacks

Store client_id securely and never expose it to end users

Use HTTPS for all API communications

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Display clear countdown timer showing OTP expiration (10 minutes)

Provide clear feedback when incorrect OTPs are entered

Offer resend OTP option after a reasonable waiting period

Implement a user-friendly error message when max attempts are reached

Code Samples

cURL

Python

Node.js

Related APIs

Generate SMS OTP: Initiates the OTP verification process by sending an OTP to a mobile number

Resend SMS OTP: Generates and sends a new OTP when the previous one expires or is lost

Verify Mobile Number: Direct verification of mobile numbers without OTP

Compliance and Legal Considerations

When implementing SMS OTP verification, ensure compliance with local telecommunications regulations and data protection laws such as GDPR or CCPA. Store verification data only for the minimum time necessary and ensure proper consent is obtained from users before initiating SMS communications.

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

{ "data": { "client_id": "send_sms_otp_xYrDQJCymqltgNgbmTfT", "mobile": "7042174106", "otp_sent": true, "otp_verified": true }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Submit OTP

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

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