RC To Fastag Balance

Endpoint Overview

POST /api/v1/fastag/rc-to-fastag-balance

Description

This API endpoint allows you to retrieve FASTag account details and balance information by providing a vehicle's registration number (RC number) and the FASTag service provider. It offers a convenient way to check FASTag balance, account status, and vehicle information without requiring the physical tag or account number.

Key Benefits

Quickly retrieve FASTag balance using only the vehicle registration number

Access comprehensive vehicle and FASTag account details in a single API call

Verify FASTag activation status before traveling on toll roads

Determine available recharge limits to plan for future payments

Use Cases

Toll Management

Transportation

Consumer Applications

Enable toll operators to verify vehicle FASTag status before entry

Allow fleet management companies to monitor FASTag balances across their vehicle fleet

Help toll plaza systems identify vehicles with insufficient balance for proactive management

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

Request Body

Parameter	Type	Required	Description
rc_number	String	Yes	Vehicle registration number (e.g., "MH12VV1999")
provider_name	String	Yes	Name of the FASTag service provider (e.g., "idfc_first_bank")

Example Request

{
    "rc_number": "MH12VV1999",
    "provider_name": "idfc_first_bank"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the FASTag details
data.client_id	String	Unique identifier for the client request
data.rc_number	String	Vehicle registration number provided in the request
data.provider_name	String	Name of the service provider provided in the request
data.provider_code	String	Unique code identifying the FASTag provider
data.customer_name	String	Name of the FASTag account holder
data.available_recharge_limit	String	Maximum amount that can be recharged to the FASTag
data.available_balance	String	Current balance available in the FASTag account
data.tag_status	String	Current status of the FASTag (e.g., "Activated")
data.vehicle_class	String	Numeric code representing the vehicle class
data.vehicle_class_desc	String	Description of the vehicle class (e.g., "Car / Jeep / Van")
data.model_name	String or null	Model name of the vehicle if available
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "rc_to_fastag_balance_fChZGKuhyAUEMoTVKrFB",
        "rc_number": "MH12VV1234",
        "provider_name": "idfc_first_bank",
        "provider_code": "IDFC88000PATXM",
        "customer_name": "SURAJ SHRIRAM KALE",
        "available_recharge_limit": "9491",
        "available_balance": "509",
        "tag_status": "Activated",
        "vehicle_class": "4",
        "vehicle_class_desc": "Car / Jeep / Van",
        "model_name": null
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid PAN

Authentication Error

{
    "status_code": 422,
    "success": false,
    "message": "Verification Failed.",
    "message_code": "verification_failed"
}

The provided PAN number does not match the required format or contains invalid characters.

Integration Best Practices

Security Recommendations

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

Implement token refresh mechanisms to handle token expiration

Validate and sanitize RC numbers before sending to prevent injection attacks

Implement rate limiting on your end to prevent abuse of the API

User Experience Guidelines

Display FASTag balance prominently when returned from the API

Clearly indicate when a FASTag is not activated or has low balance

Provide a simple way for users to recharge their FASTag if balance is low

Cache results temporarily to reduce API calls, but refresh data before critical operations

Code Samples

cURL

Python

Node.js

Related APIs

FASTag Recharge API - Allows recharging of FASTag accounts

Vehicle Details API - Provides comprehensive vehicle information using RC number

FASTag Transaction History API - Retrieves transaction history for a FASTag account

Compliance and Legal Considerations

When using this API, ensure you have proper authorization to access the vehicle and FASTag information. The data returned by this API may contain personally identifiable information (PII) and should be handled in accordance with data protection regulations. Ensure you have appropriate consent from vehicle owners before retrieving their FASTag details.

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/fastag/rc-to-fastag-balance' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "rc_number": "MH12VV1999", "provider_name": "idfc_first_bank" }'

{ "data": { "client_id": "rc_to_fastag_balance_fChZGKuhyAUEMoTVKrFB", "rc_number": "MH12VV1234", "provider_name": "idfc_first_bank", "provider_code": "IDFC88000PATXM", "customer_name": "SURAJ SHRIRAM KALE", "available_recharge_limit": "9491", "available_balance": "509", "tag_status": "Activated", "vehicle_class": "4", "vehicle_class_desc": "Car / Jeep / Van", "model_name": null }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

RC To Fastag Balance

RC To Fastag Balance#

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

RC To Fastag Balance

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples