Maharashtra Challan - Generate OTP

Endpoint Overview

POST /api/v1/maharashtra-challan/generate-otp

Description

The Maharashtra Challan Generate OTP API initiates the verification process for accessing traffic challan information linked to a mobile number in Maharashtra. This endpoint generates and sends a One-Time Password (OTP) to the registered mobile number associated with a traffic challan account, enabling secure authentication before retrieving challan details.

This API is the first step in a two-phase verification process designed to protect user privacy and ensure authorized access to sensitive traffic violation records. By leveraging mobile number verification, the API provides a secure gateway to Maharashtra's traffic challan system while maintaining compliance with data protection standards.

Key Benefits

Secure Authentication: Implements OTP-based verification to ensure only authorized users access challan information

Real-time OTP Delivery: Instantly sends verification codes to registered mobile numbers

Privacy Protection: Validates user identity before exposing sensitive traffic violation data

Seamless Integration: Simple request structure enables quick implementation in existing applications

Use Cases

Fintech & Lending

Insurance

Vehicle Services

Loan Underwriting: Verify borrower's traffic violation history during credit assessment processes

Risk Profiling: Assess applicant reliability based on outstanding traffic challans before loan approval

Background Verification: Include traffic violation checks as part of comprehensive KYC procedures

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 YOUR_JWT_TOKEN`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
client_id	string	Yes	Unique identifier for the Maharashtra Challan client. This ID is provided during API onboarding and identifies your integration instance.
mobile_number_id	string	Yes	Unique identifier for the linked mobile number. This references a previously registered mobile number in the system that is associated with traffic challan records.

Example Request

{
    "client_id": "maharashtra_challan_afqOprZOdrcDazuUndHP",
    "mobile_number_id": "linked_mobile_RhQevbwcTapdWpfxhgkf"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the response payload
data.client_id	string	Echo of the client_id sent in the request, confirming the client context
data.input_mobile_number_id	string	Echo of the mobile_number_id sent in the request, confirming the mobile number context
data.otp_generated	boolean	Indicates whether the OTP was successfully generated and sent. `true` means OTP sent successfully
status_code	integer	HTTP status code of the response (200 for success)
success	boolean	Overall success indicator for the API call
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for programmatic handling of the response

Example Successful Response

{
    "data": {
        "client_id": "maharashtra_challan_afqOprZOdrcDazuUndHP",
        "input_mobile_number_id": "linked_mobile_RhQevbwcTapdWpfxhgkf",
        "otp_generated": true
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

Rate Limit Exceeded

{
    "data": null,
    "status_code": 400,
    "success": false,
    "message": "Invalid client_id provided",
    "message_code": "invalid_client_id"
}

Occurs when the provided client_id is not recognized or has been deactivated. Verify your client_id is correct and your account is active.

Integration Best Practices

Security Recommendations

Token Management: Store JWT tokens securely using environment variables or secure vault services. Never expose tokens in client-side code or version control systems.

HTTPS Only: Always use HTTPS endpoints to ensure encrypted data transmission. Never make API calls over unsecured HTTP connections.

Client ID Protection: Treat client_id as sensitive information. Implement proper access controls to prevent unauthorized use.

Request Validation: Validate mobile_number_id format and existence before making API calls to reduce unnecessary requests.

Error Handling: Implement comprehensive error handling to prevent sensitive information leakage through error messages.

Rate Limiting: Implement client-side rate limiting to prevent accidental or malicious abuse of the OTP generation endpoint.

User Experience Guidelines

Clear Instructions: Inform users that an OTP will be sent to their registered mobile number before initiating the request.

Delivery Time: Set user expectations about OTP delivery (typically 30-60 seconds) and provide visual feedback during the waiting period.

Resend Option: Implement a "Resend OTP" button with a cooldown timer (typically 30-60 seconds) to prevent spam while allowing legitimate retries.

OTP Validity: Inform users about OTP expiration time (usually 5-10 minutes) to encourage prompt verification.

Error Communication: Display user-friendly error messages when OTP generation fails, with actionable steps for resolution.

Mobile Number Display: Show a masked version of the mobile number (e.g., ******1234) where OTP was sent for user confirmation.

Code Samples

cURL

Python

Node.js

Related APIs

Maharashtra Challan - Verify OTP: After generating the OTP, use this endpoint to verify the OTP code and retrieve the actual challan details for the verified mobile number.

Maharashtra Challan - Fetch Details: Alternative endpoint for directly fetching challan information when OTP verification is already completed or not required based on your integration setup.

Mobile Number Linking API: Pre-requisite API to register and link mobile numbers to the system before they can be used with the challan verification workflow.

Compliance and Legal Considerations

Data Privacy: This API processes personal information (mobile numbers) and traffic violation records. Ensure compliance with India's Digital Personal Data Protection Act (DPDPA) and obtain explicit user consent before accessing their challan information.

Purpose Limitation: Use the retrieved challan data only for the specific purpose disclosed to users. Avoid secondary use or sharing of data without additional consent.

Data Retention: Implement appropriate data retention policies. Delete OTPs and temporary verification data after successful authentication or expiration.

User Rights: Provide mechanisms for users to access, correct, or delete their data as per regulatory requirements.

Audit Trails: Maintain logs of OTP generation requests for security auditing and regulatory compliance. Ensure logs are protected and retained per applicable regulations.

Third-Party Disclosure: When using this API as a service provider, clearly inform end-users that their data is being processed through Surepass's infrastructure and ensure proper data processing agreements are in place.

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/maharashtra-challan/generate-otp' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "maharashtra_challan_afqOprZOdrcDazuUndHP", "mobile_number_id": "linked_mobile_RhQevbwcTapdWpfxhgkf" }'

{ "data": { "client_id": "maharashtra_challan_afqOprZOdrcDazuUndHP", "input_mobile_number_id": "linked_mobile_RhQevbwcTapdWpfxhgkf", "otp_generated": true }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Generate OTP

Maharashtra Challan - Generate 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