Introduction

Fastag Dashboard APIs

This document includes Fastag Dashboard APIs that provide integration with the National Electronic Toll Collection (NETC) system for FASTag payments. These APIs are used for:

• Customer onboarding and management
• Fastag application submission and tracking
• Wallet management and recharge
• Transaction history and reporting
• Vehicle management
• Complaint handling

API Categories

The Fastag APIs are organized into the following categories:

1. Landing Page - Customer Summary, Transaction List, Fastag List, Get Fastag Applications
2. Onboarding APIs - Application Creation, Submission, Add vehicle, Validate tag
3. Proof of Fitment - Vehicle Fitment Details
4. Vehicle Update APIs - Initiate, submit, list, get details
5. Transaction APIs - Transaction history, statements, application transactions
6. Auto-Recharge APIs - Automatic wallet top-up configuration and OTP validation
7. Complaint APIs - Raise and track complaints

HTTP Response Codes

200 - OK: For all successful queries. Any business logic or validation error can have a response as 200 OK but the data will have status = FAILURE. Details of this behavior will be explained later in this document.

400 - Bad Request: Invalid request parameters, missing required fields, or malformed request body. Check the request payload for validation errors.

401 - Unauthorized: In case of signature mismatch, invalid credentials, or missing authentication token. The request lacks valid authentication credentials.

403 - Forbidden: Access denied - insufficient permissions to access the requested resource. User is authenticated but not authorized.

404 - Not Found: The requested resource (API endpoint or data) does not exist or has been removed.

500 - Internal Server Error: This error will only come in case any of the internal service is down. Some examples are network issue, server crashes, database connection failures, or unhandled exceptions.

Fastag API Response Codes

Fastag Dashboard APIs use the following response codes in the response_code field:

Response Code	Description
00	Success - Request completed successfully
BAD_REQUEST	Invalid request parameters or format
UNAUTHORIZED	Authentication failed or missing credentials
FORBIDDEN	Access denied - insufficient permissions
INTERNAL_SERVER_ERROR	Internal server error
CUSTOMER_NOT_FOUND	Customer not found
APPLICATION_NOT_FOUND	Fastag application not found
INVALID_REQUEST	Request validation failed
OTP_ALREADY_ACTIVE	OTP already active - please wait or wait for expiry
NO_ACTIVE_OTP	No active OTP found
OTP_REFERENCE_MISMATCH	OTP reference mismatch
OTP_GENERATION_ERROR	OTP generation failed
OTP_VALIDATION_ERROR	OTP validation failed
WALLET_INELIGIBLE	Wallet not eligible for operation
WALLET_CREDIT_FREEZE	Wallet is credit-frozen
WALLET_DEBIT_FREEZE	Wallet is debit-frozen
WALLET_FREEZE	Wallet is completely frozen
WALLET_CLOSED	Wallet is closed
WALLET_NOT_FOUND	Wallet not found
WALLET_INACTIVE	Wallet is inactive
WALLET_LIMIT_EXCEEDED	Wallet limit exceeded
ACTIVE_TRANSACTION_EXISTS	Transaction already in progress
INCOMPLETE_CUSTOMER_DETAILS	Customer details incomplete
NOT_FOUND	Request resource not found
SMS_ERROR	SMS sending failed
REPLAYED_REQUEST_ERROR	Request already processed
REQUEST_DECODE_FAILURE	Request decode failed
INVALID_REQUEST_PAYLOAD	Invalid request payload
RECHARGE_FAILED	Wallet recharge failed
AUTO_RECHARGE_ENABLE_FAILED	Auto-recharge enable failed
VALIDATION_ERROR	Validation error
DATABASE_ERROR	Database error

Note:

For Fastag APIs, always check the status field first. If status is FAILURE, check response_code and response_message for error details.

Request Structure

Headers

{
  "x-client-source": "811",
  "Authorization": Bearer <session_token>,
  "x-customer-crn": "100196918"
}

For Fastag Dashboard APIs, all the request must have following headers.

Header Name	Description	Required
x-client-source	Source of the request ("811")	Yes
Authorization	OAuth Bearer token	Yes
x-customer-crn	Customer Reference Number (CRN)	Yes

Response Structure

{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Request Success",
  "payload": {
    // API-specific response data
  }
}

Parameter	Data Type	Description
status	String	"SUCCESS" or "FAILURE"
response_code	String	Response code (e.g., "00", "BAD_REQUEST", etc.,)
response_message	String	Human-readable message
payload	Object/Array	API-specific response data (null on error)

Success Response Example

{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Request Success",
  "payload": {
    "customerDetails": {
      "crn": "100196918",
      "mobileNumber": "9876543210"
    }
  }
}

Failure Response Example

{
  "status": "FAILURE",
  "response_code": "CUSTOMER_NOT_FOUND",
  "response_message": "Customer not found",
  "payload": null
}

Landing Page

Customer Summary

Retrieves the customer's information including Wallet and Fastag details.

Endpoint: GET /api/v1/fastag/dashboard/customer/summary

curl -L -X GET '{{host}}/api/v1/fastag/dashboard/customer/summary' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \

# Response: 200 OK
{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Customer summary retrieved successfully",
  "payload": {
    "customer_details": {
      "customer_id": "CUST_123456",
      "customer_seq_id": "SEQ_001",
      "crn": "100196918",
      "mobile_number": "9876543210",
      "customer_name": "John Doe",
      "kyc_status": "FKYC",
      "email_address": "john.doe@example.com",
      "delivery_address": {},
      "total_active_tags": 2,
      "total_tag_count": 2,
      "auto_recharge_enabled": true,
      "auto_recharge_wallet": "MASTER",
      "is_wallet_closure_application_raised": false
    },
    "wallet_details": [],
    "fastag_details": []
  }
}

Response Parameters:

Parameter	Data Type	Description
customerDetails	Object(Customer Details Object)	Customer information
walletDetails	Array(Wallet Details Object)	List of wallet information
fastagDetails	Array(Fastag Detail Object)	List of Fastag details

Error Codes:

Error Code	Description
BAD_REQUEST	Customer not registered / Customer not found
INTERNAL_SERVER_ERROR	Failed to retrieve customer summary

Customer Details Object

Parameter	Data Type	Description
customer_id	String	Internal customer ID
customer_seq_id	String	Customer sequence ID
crn	String	Customer Reference Number
mobile_number	String	Customer mobile number
customer_name	String	Customer name
kyc_status	String	KYC verification status (LKYC, FKYC)
email_address	String	Customer email
delivery_address	Object(Delivery Details Object)	Delivery address details
total_active_tags	Number	Count of active tags
total_tag_count	Number	Total tag count
auto_recharge_enabled	Boolean	Whether auto-recharge is enabled
auto_recharge_wallet	String	Auto-recharge wallet type. See FastagWalletType
is_wallet_closure_application_raised	Boolean	Whether wallet closure application has been raised

Delivery Details Object

Parameter	Data Type	Description
address_line1	String	Address line 1
address_line2	String	Address line 2
address_line3	String	Address line 3
city	String	City
state	String	State
pincode	String	Pincode

Wallet Details Object

Parameter	Data Type	Description
balance	String	Wallet balance
status	String	Wallet status. See WalletStatus
wallet_type	String	Wallet type. See WalletType

Fastag Detail Object

Parameter	Data Type	Description
fastag_id	String	Fastag ID
vehicle_id	String	Vehicle ID
tag_id	String	Tag ID
tid	String	Transducer ID
tag_serial_number	String	Tag serial number
barcode	String	Barcode
fastag_status	String	Fastag status. See FastagStatus
vrn	String	Vehicle registration number
vin	String	Vehicle identification number
vehicle_class	String	Vehicle class. See VehicleClass
kyv_application_id	String	KYV application ID (optional)
kyv_application_ref_id	String	KYV application reference ID (optional)
kyv_status	String	KYV application status. See KyvApplicationStatus
tag_register_date	DateTime	Tag registration date (UTC)
security_deposit	Decimal	Security deposit amount
tag_cost	Decimal	Tag cost
exception_codes	Array(Exception Code Detail Object)	Active exception codes
mobile_number	String	Registered mobile number
is_commercial_vehicle	Boolean	Commercial vehicle flag

Exception Code Detail Object

Parameter	Data Type	Description
code	String	Exception code
remarks	String	Remarks (optional)

Transaction List

Lists all transactions for the customer with filtering and pagination.

Endpoint: POST /api/v1/fastag/dashboard/customer/transactions/list

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/transactions/list' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "page_no": 0,
  "page_size": 10,
  "status": ["SUCCESS"],
  "initiation_start_time": "2024-01-01T00:00:00Z",
  "initiation_end_time": "2024-01-31T23:59:59Z"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Success",
  "payload": {
    "transactions": [
      {
        "id": "TXN_123456",
        "gateway_ref_id": "GW_REF_789",
        "amount": "150.75",
        "transaction_init_timestamp": "2024-01-15T10:30:00Z",
        "transaction_processing_time": "2024-01-15T10:31:00Z",
        "transaction_type": "DEBIT_TOLL",
        "plaza_name": "KIAL Toll Plaza",
        "vrn": "KA01AB1234",
        "vin": "CHASSIS123456",
        "tag_id": "TAG123456",
        "transaction_description": "Toll payment",
        "txn_narration": "Narration text"
      }
    ],
    "summary_details": {
      "total_row_count": 10
    }
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
vehicle_list	Array	List of vehicle IDs to filter	No
page_no	Number	Page number (0-indexed)	Yes
page_size	Number	Items per page (10, 20, 50)	Yes
status	Array(Enum)	Filter by transaction status. See DbTransactionStatus	No
initiation_start_time	String	Start time in RFC3339 format	Yes
initiation_end_time	String	End time in RFC3339 format	Yes
sources	Array(Enum)	Filter by transaction source. See FastagTransactionSource	No
transaction_types	Array(Enum)	Filter by transaction type. See DbTransactionType	No

Response Parameters:

Parameter	Data Type	Description
transactions	Array(Transaction Detail Object)	List of transactions
summary_details	Object(Summary Details Object)	Pagination summary

Transaction Detail Object

Parameter	Data Type	Description
id	UUID	Internal transaction ID
gateway_ref_id	String	Gateway transaction reference ID
amount	String	Transaction amount
transaction_init_timestamp	DateTime	When transaction was initiated
transaction_processing_time	DateTime	When transaction was processed
transaction_type	String	Transaction type. See DbTransactionType
transaction_status	String	Transaction status. See DbTransactionStatus
wallet_type	String	Type of wallet
wallet_transaction_id	UUID	Internal wallet transaction identifier
plaza_name	String	Toll plaza name
vrn	String	Vehicle registration number
vin	String	Vehicle identification number
tag_id	String	Fastag tag ID
transaction_description	String	Human-readable description
txn_narration	String	Transaction narration

Summary Details Object

Parameter	Data Type	Description
total_row_count	Integer	Total number of matching records

Error Codes:

Error Code	Description
BAD_REQUEST	Customer not registered
INTERNAL_SERVER_ERROR	Failed to list transactions

List Fastags

Lists all Fastags associated with the customer with filtering and pagination.

Endpoint: POST /api/v1/fastag/dashboard/customer/fastags/list

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/fastags/list' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "crn": "100196918",
  "page_no": 1,
  "page_size": 10,
  "status": ["ACTIVE"],
  "send_fastag_exception_codes": true,
  "vrn": "MH01AB1234",
  "tag_id": "1234567890ABCDEF12345678",
  "mobile_number": "9876543210",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-12-31T23:59:59Z",
  "orderby": "asc"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Request Success",
  "payload": {
    "fastag_details": [
      {
        "customer_ref_id": "100196918",
        "fastag_id": "550e8400-e29b-41d4-a716-446655440000",
        "vehicle_id": "660e8400-e29b-41d4-a716-446655440000",
        "tag_id": "1234567890ABCDEF12345678",
        "tid": "TID123456",
        "tag_serial_number": "SN123456",
        "barcode": "BC123456",
        "fastag_status": "ACTIVE",
        "vrn": "MH01AB1234",
        "vin": "CHASSIS123456",
        "vehicle_class": "VC4",
        "tag_register_date": "2024-01-15T10:30:00Z",
        "security_deposit": 200.00,
        "tag_cost": 100.00,
        "mobile_number": "9876543210",
        "exception_code_details": []
      }
    ],
    "total_pages": 1
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
crn	String	Customer Reference Number (auto-set from session)	No
page_no	Number	Page number (1-indexed)	Yes
page_size	Number	Items per page	Yes
status	Array(FastagStatus)	Filter by Fastag status	Yes
send_fastag_exception_codes	Boolean	Include exception codes in response	Yes
vrn	String	Filter by vehicle registration number	No
tag_id	String	Filter by tag ID	No
mobile_number	String	Filter by mobile number	No
start_time	String	Start date in RFC3339 format	No
end_time	String	End date in RFC3339 format	No
orderby	String - See OrderBy	Sort order	No

Response Parameters:

Parameter	Data Type	Description
fastag_details	Array(Fastag Details Object)	List of Fastag details
total_pages	Number	Total number of pages available

Fastag Details Object

Parameter	Data Type	Description
customer_ref_id	String	Customer reference ID
fastag_id	String	Fastag ID
vehicle_id	String	Vehicle ID
tag_id	String	Tag ID
tid	String	Tag TID
tag_serial_number	String	Tag serial number
barcode	String	Barcode
fastag_status	String - See FastagStatus	Fastag status
vrn	String	Vehicle registration number (optional)
vin	String	Vehicle identification number (chassis)
vehicle_class	String - See VehicleClass	Vehicle class
tag_register_date	String	Tag registration date (ISO 8601)
security_deposit	Decimal	Security deposit amount
tag_cost	Decimal	Tag cost
mobile_number	String	Mobile number
exception_code_details	Array(Exception Code Details Object)	Exception code details (optional)

Exception Code Details Object

Parameter	Data Type	Description
exc_code	String	Exception code
source	String - See ExceptionSource	Exception source
status	String - See ExceptionCodeStatus	Exception code status
start_time	String	Start time (ISO 8601)
end_time	String	End time (ISO 8601, optional)

Error Codes:

Error Code	Description
UNAUTHORIZED	Session not valid
BAD_REQUEST	Customer not found / Request limit exceeded / Validation error
INTERNAL_SERVER_ERROR	Internal server error

Get Latest Fastag Applications

Fetches all the application associated with the customer's CRN.

Endpoint: GET /api/v1/fastag/dashboard/customer/applications/latest

curl -L -X GET '{{host}}/api/v1/fastag/dashboard/customer/applications/latest' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{}'

# Response: 200 OK
{
  "response_code": "00",
  "response_message": "Request Success",
  "status": "SUCCESS",
  "payload": {
    "application_details": {
      "applicationId": "dcb2691b-1980-4a95-a8a5-dc7c40cefeb7",
      "applicationRefId": "FA8BD95CEC9D85467ABEDD8A0C3CDC0FAB",
      "applicationStatus": "PAYMENT_INITIATED",
      "crn": "909461524",
      "deliveryAddress": {
        "address_1": "123 Main St",
        "address_2": "Apt 4B",
        "address_3": "Near City Center",
        "city": "Mumbai",
        "pincode": "400001",
        "state": "MH"
      },
      "email": "john.doe@example.com",
      "fullName": "John Doe",
      "mobileNumber": "6545123313"
    },
    "refund_details": [],
    "transaction_details": [
      {
        "amount": "600.00",
        "orderId": "pg_09c275d8-a87c-4beb-a38c-5c89f18bbf4d",
        "paymentMode": "PG",
        "transactionCompletionDate": null,
        "transactionId": "a3ea86e4094649d4bcacf6fe858f42fd",
        "transactionInitiationDate": "2026-04-29 15:31:26.692273 +00:00",
        "transactionStatus": "PENDING"
      }
    ],
    "vehicle_details": [
      {
        "applicationId": "dcb2691b-1980-4a95-a8a5-dc7c40cefeb7",
        "pricing": {
          "initial_wallet_load": "300.00",
          "non_discounted_tag_price": "100.00",
          "tag_cost_breakdown": {
            "gst": "15.25",
            "tag_cost_base": "84.75"
          },
          "tag_price": "100.00",
          "tag_security_deposit": "200.00",
          "vc": "VC4",
          "vehicle_linking_id": "87f5881c-3655-4d4f-ae0f-223acb763d29"
        },
        "rcDocuments": [
          {
            "extension": "jpeg",
            "path": "909461524/dcb2691b-1980-4a95-a8a5-dc7c40cefeb7/87f5881c-3655-4d4f-ae0f-223acb763d29/RC_F",
            "remarks": null,
            "reupload_count": 0,
            "reupload_path": null,
            "status": "PENDING",
            "status_updated_at": null,
            "type": "RC_F",
            "upload_at": "2026-04-29T15:31:13.450566Z"
          },
          {
            "extension": "jpeg",
            "path": "909461524/dcb2691b-1980-4a95-a8a5-dc7c40cefeb7/87f5881c-3655-4d4f-ae0f-223acb763d29/RC_B",
            "remarks": null,
            "reupload_count": 0,
            "reupload_path": null,
            "status": "PENDING",
            "status_updated_at": null,
            "type": "RC_B",
            "upload_at": "2026-04-29T15:31:13.450566Z"
          }
        ],
        "status": "SUBMITTED",
        "tagDetails": null,
        "vehicleDetails": {
          "chassisNumber": "KA09AB1234ERLF2S0",
          "documents": [
            {
              "extension": "jpeg",
              "type": "RC_F"
            },
            {
              "extension": "jpeg",
              "type": "RC_B"
            }
          ],
          "engineNumber": "ENG123456789",
          "fuelType": "PETROL",
          "gvwWeight": "12500",
          "hasTagInHand": false,
          "isCommercial": false,
          "isVahanVerified": true,
          "nationalPermit": false,
          "nationalPermitExpiry": null,
          "state": "MH",
          "vehicleClass": "VC4",
          "vehicleLinkingId": "87f5881c-3655-4d4f-ae0f-223acb763d29",
          "vehicleNumber": "KA09AB1234"
        },
        "vin": "KA09AB1234ERLF2S0",
        "vrn": "KA09AB1234"
      }
    ]
  }
}

Response Parameters:

Parameter	Data Type	Description
application_details	Object(Application Details Object)	Application details
vehicle_details	Array(Vehicle Details Object)	Array of vehicle details
transaction_details	Array(Transaction Details Object)	Transaction details
refund_details	Array(Refund Details Object)	List of refunds (empty array if none)

Application Details Object

Parameter	Data Type	Description
applicationId	String (UUID)	Unique application identifier
applicationRefId	String	Application reference ID
applicationStatus	String	Status of the application (e.g., "PAYMENT_INITIATED", "SUBMITTED", "CLOSED")
crn	String	Customer Reference Number
deliveryAddress	Object(Delivery Address Object)	Delivery address
email	String	Customer email address
fullName	String	Customer full name
mobileNumber	String	Customer mobile number

Delivery Address Object

Parameter	Data Type	Description
address_1	String	Address line 1
address_2	String	Address line 2 (nullable)
address_3	String	Address line 3 (nullable)
city	String	City
pincode	String	Pincode
state	String	State code

Vehicle Details Object

Parameter	Data Type	Description
applicationId	String (UUID)	Application ID
pricing	Object(Pricing Object)	Pricing details (optional)
rcDocuments	Array(RC Document Object)	Array of RC documents
status	String	Vehicle status (e.g., "SUBMITTED", "APPROVED")
tagDetails	Object(Tag Details Object)	Tag details (nullable)
vehicleDetails	Object(Vehicle Details Inner Object)	Vehicle details
vin	String	Vehicle Identification Number (VIN)
vrn	String	Vehicle Registration Number

Pricing Object

Parameter	Data Type	Description
initial_wallet_load	Decimal	Initial wallet load amount
non_discounted_tag_price	Decimal	Non-discounted tag price
tag_cost_breakdown	Object(Tag Cost Breakdown Object)	Tag cost breakdown
tag_price	Decimal	Final tag price
tag_security_deposit	Decimal	Security deposit amount
vc	String	Vehicle class (e.g., "VC4")
vehicle_linking_id	String (UUID)	Vehicle linking ID

Tag Cost Breakdown Object

Parameter	Data Type	Description
gst	Decimal	GST amount
tag_cost_base	Decimal	Base tag cost (before GST)

RC Document Object

Parameter	Data Type	Description
extension	String	File extension (e.g., "jpeg", "pdf")
path	String	Document storage path
remarks	String	Remarks (nullable)
reupload_count	Integer	Number of times reuploaded
reupload_path	String	Reupload path (nullable)
status	String	Document status ("PENDING", "APPROVED", "REJECTED")
status_updated_at	String	Status update timestamp (nullable)
type	String	Document type ("RC_F", "RC_B", etc.)
upload_at	String	Upload timestamp (ISO 8601)

Tag Details Object

Parameter	Data Type	Description
tagId	String	Tag ID
barcode	String	Barcode
inventoryId	String	Inventory ID

Vehicle Details Inner Object

Parameter	Data Type	Description
chassisNumber	String	Chassis/VIN number
documents	Array(Object)	Array of submitted document types. See Document Type Object
engineNumber	String	Engine number
fuelType	String	Fuel type (e.g., "PETROL")
gvwWeight	String	Gross vehicle weight
hasTagInHand	Boolean	Whether customer has physical tag
isCommercial	Boolean	Whether commercial vehicle
isVahanVerified	Boolean	Vahan verification status
nationalPermit	Boolean	National permit flag
nationalPermitExpiry	String	Permit expiry date (nullable)
state	String	State code
vehicleClass	String	Vehicle class
vehicleLinkingId	String (UUID)	Vehicle linking ID
vehicleNumber	String	Vehicle registration number

Document Type Object

Parameter	Data Type	Description
extension	String	File extension
type	String	Document type ("RC_F", "RC_B")

Transaction Details Object

Parameter	Data Type	Description
amount	Decimal	Transaction amount
orderId	String	Order ID from payment gateway
paymentMode	String	Payment mode (e.g., "PG", "WALLET")
transactionCompletionDate	String	Completion timestamp (nullable)
transactionId	String	Transaction ID
transactionInitiationDate	String	Initiation timestamp
transactionStatus	String	Transaction status ("PENDING", "SUCCESS", "FAILURE")

Refund Details Object

Parameter	Data Type	Description
refund_id	String (UUID)	Internal refund ID
transaction_id	String (UUID)	Original payment transaction ID
gateway_refund_id	String	External refund ID from payment gateway (null if not yet processed)
amount	Decimal	Refund amount
refund_type	String	"FULL" or "PARTIAL"
refund_mode	String	"GATEWAY" or "WALLET"
status	String	"PENDING", "SUCCESS", "FAILURE", etc.
created_at	String	ISO 8601 timestamp
updated_at	String	ISO 8601 timestamp
metadata	Object(Refund Metadata Object)	Additional refund details (may be null)

Refund Metadata Object

Parameter	Data Type	Description
vehicle_breakups	Array	Vehicle-wise breakup of the refund
gateway_response	Object	Response from the payment gateway
error_info	Object	Error information if the refund failed
wallet_id	String	Wallet ID if the refund was processed to the wallet

Error Codes:

Error Code	Description
UNAUTHORIZED	No active session found
APPLICATION_NOT_FOUND	No application found for this customer
INTERNAL_SERVER_ERROR	Database error or failed to fetch application/vehicle details

Auth

Generate Token

Generates an access token for server-to-server authentication.

Endpoint: POST /api/v1/fastag/dashboard/s2s/auth/token

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/s2s/auth/token' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "grant_type": "client_credentials",
  "client_id": "test-client-123",
  "client_secret": "s3cr3t_p@ssw0rd_16charsmin"
}'

# Response: 200 OK
{
  "access_token": "base64url_encoded_random_32_bytes",
  "token_type": "Bearer",
  "expires_in": 86400
}

Request Parameters:

Parameter	Data Type	Description
grant_type	String	Must be client_credentials
client_id	String	Client identifier
client_secret	String	Client secret (minimum 1 characters, maximum 256)

Response Parameters:

Parameter	Data Type	Description
access_token	String	Base64url encoded random (minimum 1 characters, maximum 256)
token_type	String	Always Bearer
expires_in	Integer	Token expiry time in seconds (86400 = 24 hours)

Error Responses:

HTTP Status	Error Code	Description
400 Bad Request	UNSUPPORTED_GRANT_TYPE	Only client_credentials grant type is supported
400 Bad Request	VALIDATION_ERROR	Validation error (e.g., missing or invalid fields)
401 Unauthorized	INVALID_CLIENT	Invalid client_id or client_secret
401 Unauthorized	INVALID_TOKEN	Token is invalid, expired, or revoked
500 Internal Server Error	SERVER_ERROR	An internal error occurred

Revoke Token

Revokes an active access token.

Endpoint: POST /api/v1/fastag/dashboard/s2s/auth/revoke

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/s2s/auth/revoke' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "token": "base64url_encoded_token",
  "client_id": "test-client-123",
  "client_secret": "s3cr3t_p@ssw0rd_16charsmin"
}'

# Response: 200 OK
{
  "message": "Token revoked successfully"
}

Request Parameters:

Parameter	Data Type	Description
token	String	The token to be revoked
client_id	String	Client identifier
client_secret	String	Client secret (minimum 1 characters, maximum 256)

Response Parameters:

Parameter	Data Type	Description
message	String	Success message

Note: Returns 200 even for invalid tokens (RFC 7009 §2.2) to prevent token enumeration.

Error Responses:

HTTP Status	Error Code	Description
400 Bad Request	UNSUPPORTED_GRANT_TYPE	Only client_credentials grant type is supported
400 Bad Request	VALIDATION_ERROR	Validation error (e.g., missing or invalid fields)
401 Unauthorized	INVALID_CLIENT	Invalid client_id or client_secret
401 Unauthorized	INVALID_TOKEN	Token is invalid, expired, or revoked
500 Internal Server Error	SERVER_ERROR	An internal error occurred

Onboarding APIs (Work in Progress)

Create Application

Creates a new Fastag application for the customer.

Endpoint: POST /api/v1/fastag/dashboard/customer/applications/create

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/applications/create' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "crn_hash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
  "mobile_number": "9876543210"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Application created successfully",
  "payload": {
    "application_id": "APP_123456",
    "application_ref_id": "APP_REF_789"
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
crn_hash	String	SHA256 hash of the Customer Reference Number (CRN)	Yes
mobile_number	String	Customer Mobile Number	Yes

Response Parameters:

Parameter	Data Type	Description
application_id	String	Unique identifier for the created application
application_ref_id	String	Application reference ID

Error Codes:

Error Code	Description
BAD_REQUEST	Invalid CRN / Validation error
WALLET_CLOSED	Wallet is closed
WALLET_CREDIT_FREEZE	Wallet is credit-frozen
WALLET_DEBIT_FREEZE	Wallet is debit-frozen
WALLET_FREEZE	Wallet is completely frozen
WALLET_INACTIVE	Wallet is inactive
WALLET_NOT_FOUND	Wallet not found
INTERNAL_SERVER_ERROR	Internal error

Submit Fastag Application

Submits the Fastag application for processing with customer and vehicle details.

Endpoint: POST /api/v1/fastag/dashboard/customer/applications/fastag/submit

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/applications/fastag/submit' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "applicationId": "550e8400-e29b-41d4-a716-446655440000",
  "fullName": "John Doe",
  "email": "john.doe@example.com",
  "mobileNumber": "9876543210",
  "deliveryAddress": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Apartment 4B",
    "city": "Mumbai",
    "state": "Maharashtra",
    "pincode": "400001"
  },
  "vehicles": [
    {
      "vehicleLinkingId": "550e8400-e29b-41d4-a716-446655440001",
      "vehicleNumber": "MH01AB1234",
      "engineNumber": "ENGINE123456",
      "chassisNumber": "CHASSIS123456",
      "state": "Maharashtra",
      "fuelType": "PETROL",
      "nationalPermit": false,
      "vehicleClass": {
        "vehicleCategory": "VC4",
        "vehicleDescription": "Car/Jeep"
      },
      "isVahanVerified": true,
      "nationalPermitExpiry": null,
      "isCommercial": false,
      "documents": [
        {
          "type": "RcF",
          "extension": "pdf"
        }
      ],
      "hasTagInHand": false
    }
  ],
  "optedMasterWallet": true,
  "channel": "811"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Application submitted successfully",
  "payload": {
    "message": "Application submitted successfully",
    "applicationId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
applicationId	String (UUID)	Application ID to submit	Yes
fullName	String	Customer's full name	Yes
email	String	Customer's email address	No
mobileNumber	String	Customer's mobile number (10 digits)	Yes
deliveryAddress	Object(Delivery Details Object)	Delivery address for Fastag	Yes
vehicles	Array(Vehicle Object)	List of vehicle details	Yes
optedMasterWallet	Boolean	Whether master wallet is opted	No
channel	String - See ApplicationChannel	Application channel	Yes

Response Parameters:

Parameter	Data Type	Description
message	String	Response message
applicationId	String	Submitted application ID

Vehicle Object

Parameter	Data Type	Description	Required
gvwWeight	String	Gross vehicle weight	No
vehicleLinkingId	UUID	Vehicle linking ID	Yes
vehicleNumber	String	Vehicle registration number (VRN)	Yes
engineNumber	String	Engine number	Yes
chassisNumber	String	Chassis/VIN number	Yes
state	String	State of registration	Yes
fuelType	String	Fuel type (e.g., PETROL, DIESEL)	Yes
nationalPermit	Boolean	Whether vehicle has national permit	No
vehicleClass	Object	Vehicle class details	Yes
isVahanVerified	Boolean	Whether vehicle details are verified with Vahan	No
nationalPermitExpiry	String	National permit expiry date (if applicable)	No
isCommercial	Boolean	Whether vehicle is commercial	No
documents	Array(Submitted RC Document Details)	List of submitted RC documents	Yes
hasTagInHand	Boolean	Whether customer already has the physical tag	No

Submitted RC Document Details

Parameter	Data Type	Description	Required
type	Enum	Document type (See DocumentType)	Yes
extension	String	File extension (e.g., pdf, jpg)	Yes

Error Codes:

Error Code	Description
BAD_REQUEST	Application not found / Validation error
DOCUMENT_NOT_UPLOADED	RC document not generated for vehicle
VAHAN_DETAILS_MISMATCH	Vahan details mismatch for vehicle
UNAUTHORIZED	User is not authorized to perform this action

| VEHICLE_ALREADY_REGISTERED | Vehicle is already registered with another Fastag | | WALLET_CLOSED | Wallet is closed | | WALLET_CREDIT_FREEZE | Wallet is credit-frozen | | WALLET_DEBIT_FREEZE | Wallet is debit-frozen | | WALLET_FREEZE | Wallet is completely frozen | | WALLET_INACTIVE | Wallet is inactive | | WALLET_NOT_FOUND | Wallet not found | | INTERNAL_SERVER_ERROR | Failed to process request |

Link Tag (Tag in Hand)

Links a physical tag to a vehicle after receiving it.

Endpoint: POST /api/v1/fastag/dashboard/customer/applications/fastag/tag/link

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/applications/fastag/tag/link' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "vehicle_info_id": "550e8400-e29b-41d4-a716-446655440001",
  "tag_identifier": {
    "tag_id": "1234567890ABCDEF12345678"
  }
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Tag assigned successfully",
  "payload": {}
}

Request Parameters:

Parameter	Data Type	Description	Required
application_id	String (UUID)	Application ID	Yes
vehicle_info_id	String (UUID)	Vehicle info ID to link tag to	Yes
tag_identifier	Object	Tag identification (Enum: TagId or Barcode)	Yes

tag_identifier (Enum - one of the following):

Variant	Parameters	Data Type	Description
Barcode	serial_number	Number	Serial number from barcode
	issuer_key_index	Number	Issuer key index
	issuer_iin	Number	Issuer IIN
TagId	tag_id	String	Direct tag ID (24 or 32 hex characters)

Error Codes:

Error Code	Description
BAD_REQUEST	Validation error / Tag not found / Invalid vehicle info status / Tag already assigned / Tag cannot be linked / Vehicle info does not belong to application
UNAUTHORIZED	Not authorized to perform this action
TAG_NOT_AVAILABLE	Tag is invalid or not available
INTERNAL_SERVER_ERROR	Internal error

List Customer Applications

Lists all Fastag applications for the customer.

Endpoint: POST /api/v1/fastag/dashboard/customer/applications/list

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/applications/list' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "page": 1,
  "page_size": 10
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Applications retrieved successfully",
  "payload": {
    "applications": [],
    "totalPages": 1,
    "totalItems": 0
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
page	Number	Page number	No
page_size	Number	Items per page	No

Response Parameters:

Parameter	Data Type	Description
applications	Array(Customer Application Details Object)	List of customer applications
totalPages	Number	Total number of pages
totalItems	Number	Total number of items

Customer Application Details Object

Parameter	Data Type	Description
applicationId	String (UUID)	Unique application identifier
applicationRefId	String	Application reference ID
vehicleLinkingId	String (UUID)	Vehicle linking ID
applicationStatus	String - See FastagApplicationStatus	Application status
kycStatus	String	KYC verification status (LKYC, FKYC)
optedMasterWallet	Boolean	Whether master wallet is opted
vrn	String	Vehicle registration number (optional)
vin	String	Vehicle identification number
vehicleStatus	String - See FastagAppInfoStatus	Vehicle info status
vehicleClass	String - See VehicleClass	Vehicle class
state	String	State code
nationalPermit	Boolean	Whether national permit is available
nationalPermitExpiry	String	National permit expiry date (optional)
isVahanVerified	Boolean	Whether Vahan verification is done
isCommercial	Boolean	Whether vehicle is commercial
gvwWeight	String	Gross vehicle weight (optional)
fuelType	String	Fuel type
engineNumber	String	Engine number

Error Codes:

Error Code	Description
BAD_REQUEST	CRN not found for customer / Validation error
INTERNAL_SERVER_ERROR	Internal server error

Create Application Transaction

Creates a transaction for an application.

Endpoint: POST /api/v1/fastag/dashboard/customer/applications/transactions

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/applications/transactions' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "application_id": "APP_123456",
  "instrument_type": "WALLET",
  "instrument_id": "wallet-uuid-here"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Transaction created successfully",
  "payload": {
    "transaction_id": "TXN_123456",
    "order_id": "ORDER_789",
    "payment_mode": "WALLET"
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
application_id	UUID	Application ID	Yes
instrument_type	String	Payment instrument type.	Yes
instrument_id	String	Instrument identifier.	No

Response Parameters:

Parameter	Data Type	Description
transaction_id	String	Created transaction ID
order_id	String	Order ID (if applicable)
payment_mode	String	Payment mode used

Error Codes:

Error Code	Description
BAD_REQUEST	Invalid application status, application not found, invalid wallet ID, wallet not found, wallet not authorized, wallet not applicable, or validation error
ACTIVE_TRANSACTION_EXISTS	An active transaction already exists for this application
WALLET_INELIGIBLE	Wallet is not eligible for transaction
INTERNAL_SERVER_ERROR	Missing order ID, missing pricing details, or internal server error

Application Transaction Status

Gets the status of an application transaction.

Endpoint: POST /api/v1/fastag/dashboard/customer/applications/transactions/status

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/applications/transactions/status' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "application_id": "APP_123456",
  "transaction_id": "TXN_123456"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Transaction status retrieved successfully",
  "payload": {
    "status": "PENDING"
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
application_id	UUID	Application ID	Yes
transaction_id	String	Transaction ID	Yes

Response Parameters:

Parameter	Data Type	Description
status	String	Transaction status

Error Codes:

Error Code	Description
BAD_REQUEST	Transaction not found, application not found, or validation error
UNAUTHORIZED	Not authorized to view this transaction
INTERNAL_SERVER_ERROR	Database error, payment client error, missing transaction status, or internal server error

Get Application Invoice

Retrieves the invoice for a specific application.

Endpoint: GET /api/v1/fastag/dashboard/customer/applications/{application_id}/invoice

curl -L -X GET '{{host}}/api/v1/fastag/dashboard/customer/applications/APP_123456/invoice' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Invoice retrieved successfully",
  "payload": {
    "applicationDetails": {
      "applicationId": "550e8400-e29b-41d4-a716-446655440000",
      "applicationRefId": "APP_123456",
      "fullName": "John Doe",
      "email": "john@example.com",
      "mobileNumber": "9876543210",
      "crn": "100196918",
      "applicationStatus": "SUBMITTED",
      "deliveryAddress": {
        "addressLine1": "123 Main Street",
        "addressLine2": "Apt 4B",
        "city": "Mumbai",
        "state": "MH",
        "pincode": "400001"
      }
    },
    "vehicleDetails": [
      {
        "vehicleInfo": {
          "applicationId": "550e8400-e29b-41d4-a716-446655440000",
          "vrn": "MH01AB1234",
          "vin": "MA1ABC123XYZ456789",
          "status": "SUBMITTED",
          "rcDocuments": [
            {
              "type": "RC_F",
              "path": "https://example.com/rc_front.jpg",
              "status": "APPROVED"
            }
          ],
          "vehicleDetails": {
            "gvwWeight": "1500",
            "vehicleLinkingId": "550e8400-e29b-41d4-a716-446655440001",
            "vehicleNumber": "MH01AB1234",
            "engineNumber": "ABC123XYZ789",
            "chassisNumber": "MA1ABC123XYZ456789",
            "state": "MH",
            "fuelType": "PETROL",
            "nationalPermit": false,
            "nationalPermitExpiry": null,
            "vehicleClass": "VC1",
            "isVahanVerified": true,
            "isCommercial": false,
            "documents": [
              {
                "type": "RcF",
                "extension": "pdf"
              }
            ],
            "hasTagInHand": false
          },
          "tagDetails": {
            "tagId": "1234567890ABCDEF12345678",
            "barcode": "1234567890123",
            "inventoryId": "TAG_INV_001"
          }
        },
        "pricing": {
          "vehicleClass": "VC1",
          "tagPrice": 100.00,
          "nonDiscountedTagPrice": 120.00,
          "securityDeposit": 200.00,
          "fastagAmount": 500.00,
          "vehicleLinkingId": "550e8400-e29b-41d4-a716-446655440001",
          "tagCostBase": 100.00,
          "gst": 18.00
        }
      }
    ],
    "transactionDetails": [
      {
        "transactionId": "TXN_123456",
        "orderId": "ORD_123456",
        "amount": "500.00",
        "paymentMode": "UPI",
        "transactionInitiationDate": "2024-01-15T10:30:00Z",
        "transactionCompletionDate": "2024-01-15T10:30:05Z",
        "transactionStatus": "SUCCESS"
      }
    ],
    "totalPrice": 800.00,
    "totalDeliveryCharge": 50.00
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
applicationId	String (UUID)	Application ID	Yes

Response Parameters:

Parameter	Data Type	Description
applicationDetails	Object(Application Details Object)	Application details
vehicleDetails	Array(Vehicle Invoice Details Object)	Array of vehicle invoice objects
transactionDetails	Array(Transaction Details Object)	Transaction details
totalPrice	Decimal	Total price amount
totalDeliveryCharge	Decimal	Total delivery charge

Application Details Object

Parameter	Data Type	Description
applicationId	String	Application ID
applicationRefId	String	Application reference ID
fullName	String	Customer full name
email	String	Customer email (optional)
mobileNumber	String	Customer mobile number
crn	String	Customer reference number
applicationStatus	String - See FastagApplicationStatus	Application status
deliveryAddress	Object(Delivery Details Object)	Delivery address (optional)

Vehicle Invoice Details Object

Parameter	Data Type	Description
vehicleInfo	Object(Vehicle Info Response Object)	Vehicle information
pricing	Object(Vehicle Pricing Response Object)	Pricing details

Vehicle Info Response Object

Parameter	Data Type	Description
applicationId	String (UUID)	Application ID
vrn	String	Vehicle registration number (optional)
vin	String	Vehicle identification number
status	String - See FastagAppInfoStatus	Vehicle info status
rcDocuments	Array(RC Documents Object)	RC documents (Array of DocumentInformation)
vehicleDetails	Object(Vehicle Details Object)	Vehicle details
tagDetails	Object(Tag Details Object)	Tag details (optional)

Vehicle Pricing Response Object

Parameter	Data Type	Description
vc	String - See VehicleClass	Vehicle class
tag_price	Decimal	Tag price
non_discounted_tag_price	Decimal	Non-discounted tag price
tag_security_deposit	Decimal	Tag security deposit
initial_wallet_load	Decimal	Initial wallet load
vehicle_linking_id	String	Vehicle linking ID (UUID)
tag_cost_breakdown	Object(Tag Cost Breakdown Object)	Tag cost breakdown

Tag Cost Breakdown Object

Parameter	Data Type	Description
tag_cost_base	Decimal	Base tag cost (before GST)
gst	Decimal	GST amount

Tag Details Object

Parameter	Data Type	Description
tagId	String	Tag ID
barcode	String	Barcode
inventoryId	String	Inventory ID

RC Documents Object

Parameter	Data Type	Description
documents	Array(Document Information Object)	Array of document information

Document Information Object

Parameter	Data Type	Description
type	String - See DocumentType	Document type
path	String	Document path/URL
reuploadPath	String	Reupload path (optional)
extension	String	File extension (optional)
status	String - See DocumentStatus	Document status
remarks	String	Remarks (optional)
statusUpdatedAt	String	Status update timestamp (optional)
uploadAt	String	Upload timestamp (optional)
reuploadCount	Number	Number of reuploads

Vehicle Details Object

Parameter	Data Type	Description
gvwWeight	String	Gross vehicle weight (optional)
vehicleLinkingId	String (UUID)	Vehicle linking ID
vehicleNumber	String	Vehicle registration number
engineNumber	String	Engine number
chassisNumber	String	Chassis number
state	String	State code
fuelType	String	Fuel type
nationalPermit	Boolean	National permit flag
nationalPermitExpiry	String	National permit expiry date (optional)
vehicleClass	String - See VehicleClass	Vehicle class
isVahanVerified	Boolean	Whether vehicle details are verified with Vahan
isCommercial	Boolean	Whether vehicle is commercial
documents	Array(Submitted RC Document Details)	Submitted RC documents
hasTagInHand	Boolean	Whether customer already has the physical tag (optional)

Transaction Details Object

Parameter	Data Type	Description
transactionId	String	Transaction ID
orderId	String	Order ID (optional)
amount	String	Transaction amount
paymentMode	String	Payment mode
transactionInitiationDate	String	Transaction initiation date
transactionCompletionDate	String	Transaction completion date (optional)
transactionStatus	String - See DbTransactionStatus	Transaction status

Error Codes:

Error Code	Description
BAD_REQUEST	Invalid application ID format
UNAUTHORIZED	Not authorized to view this application
FETCHING_APPLICATION_FAILED	Failed to fetch application details

Get Vahan Details

Fetches vehicle details from Vahan (transport department database).

Endpoint: POST /api/v1/fastag/dashboard/customer/vehicle/vahan-details

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/vehicle/vahan-details' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "vrn": "MH01AB1234"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Vahan details retrieved successfully",
  "payload": {
    "vrn": "MH01AB1234",
    "vin": "MA1ABC123XYZ456789",
    "engine_number": "ENG123456",
    "region_state": "MH",
    "fuel_type": "PETROL",
    "is_national_permit": false,
    "model": "Swift",
    "chassis_number": "MA1ABC123XYZ456789",
    "national_permit_end_date": "2025-12-31",
    "gvw": "1500",
    "registered_vehicle": "YES",
    "vehicle_descriptor": "CAR"
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
vrn	String	Vehicle Registration Number	No
vin	String	Vehicle Identification Number	No
engineNumber	String	Engine Number	Yes

Response Parameters:

Parameter	Data Type	Description
vrn	String	Vehicle Registration Number
vin	String	Vehicle Identification Number
engine_number	String	Engine Number
region_state	String	Region/State code
fuel_type	String	Fuel type
is_national_permit	Boolean	National permit status
model	String	Vehicle model
chassis_number	String	Chassis number
national_permit_end_date	String	National permit end date
gvw	String	Vehicle Weight
registered_vehicle	String	Registered vehicle status
vehicle_descriptor	String	Vehicle descriptor

Error Codes:

Error Code	Description
BAD_REQUEST	Validation error
VALIDATION_ERROR	Incorrect vehicle details entered
VEHICLE_NOT_FOUND	Vehicle not found in Vahan database (allows manual entry)
NETC_ERROR	NETC service error or timeout
VAHAN_TIMEOUT	Vahan service timeout
NO_RESPONSE	No response from NETC service (allows manual entry)
REGISTRATION_NOT_ALLOWED	Vehicle registration not allowed
INTERNAL_ERROR	Internal error

Get Tag Pricing Info

Fetches the current tag pricing information for an application.

Endpoint: POST /api/v1/fastag/dashboard/customer/tag-price/fetch

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/tag-price/fetch' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "channelName": "DEFAULT",
  "applicationId": "550e8400-e29b-41d4-a716-446655440000"
}'

Request Parameters:

Parameter	Data Type	Description
channelName	String - See FastagChannel	Channel name
applicationId	String	Application ID (UUID)

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Tag pricing retrieved successfully",
  "payload": {
    "channel_name": "DEFAULT",
    "vehicles": [
      {
        "vc": "VC4",
        "tag_price": 100.00,
        "non_discounted_tag_price": 120.00,
        "tag_security_deposit": 200.00,
        "initial_wallet_load": 100.00,
        "vehicle_linking_id": "550e8400-e29b-41d4-a716-446655440000",
        "tag_cost_breakdown": {
          "tag_cost_base": 100.00,
          "gst": 18.00
        }
      }
    ],
    "total_initial_wallet_load": 100.00,
    "total_tag_cost": 100.00,
    "total_non_discounted_tag_price": 120.00,
    "total_security_deposit": 200.00,
    "total_price": 300.00,
    "total_delivery_charge": 50.00,
    "total_tag_cost_breakdown": {
      "tag_cost_base": 100.00,
      "gst": 18.00
    }
  }
}

Response Parameters:

Parameter	Data Type	Description
channel_name	String	Channel name
vehicles	Array(Vehicle Pricing Response Object)	List of vehicle pricing details
total_initial_wallet_load	Decimal	Total initial wallet load amount
total_tag_cost	Decimal	Total tag cost
total_non_discounted_tag_price	Decimal	Total non-discounted tag price
total_security_deposit	Decimal	Total security deposit
total_price	Decimal	Total price (tag cost + security deposit + delivery charge)
total_delivery_charge	Decimal	Total delivery charge
total_tag_cost_breakdown	Object(Tag Cost Breakdown Object)	Total tag cost breakdown

Error Codes:

Error Code	Description
BAD_REQUEST	Validation error
01	Failed to fetch tag pricing info

Add Vehicle

Adds a vehicle to an existing Fastag application.

Endpoint: POST /api/v1/fastag/dashboard/customer/vehicle/add

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/vehicle/add' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "applicationId": "550e8400-e29b-41d4-a716-446655440000",
  "vehicleNumber": "MH01AB1234",
  "engineNumber": "ENG123456789",
  "chassisNumber": "CHASSIS123456",
  "state": "Maharashtra",
  "fuelType": "Petrol",
  "nationalPermit": false,
  "vehicleClass": "CAR",
  "isCommercial": false,
  "isVahanVerified": false
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Vehicle added successfully",
  "payload": {
    "vehicleLinkingId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
applicationId	String	Application UUID	Yes
vehicleLinkingId	String	Vehicle linking ID (UUID, optional)	No
vehicleNumber	String	Vehicle Registration Number (VRN)	Yes
engineNumber	String	Engine number	Yes
chassisNumber	String	Chassis number (VIN)	Yes
state	String	State of registration	Yes
fuelType	String	Fuel type (Petrol/Diesel/CNG/Electric)	Yes
nationalPermit	Boolean	Whether vehicle has national permit	No
vehicleClass	String - See VehicleClass	Vehicle class	Yes
isVahanVerified	Boolean	Whether vehicle is Vahan verified	No
nationalPermitExpiry	String	National permit expiry date (YYYY-MM-DD)	No
isCommercial	Boolean	Whether vehicle is commercial	No
gvwWeight	String	Gross vehicle weight (for commercial vehicles)	No
tagId	String	Tag ID for tag-in-hand flow	No
rcDocuments	Array(Uploaded Document Info Object)	RC document details	No

Response Parameters:

Parameter	Data Type	Description
vehicleLinkingId	String	Unique identifier for the vehicle linking

Error Codes:

Error Code	Description
BAD_REQUEST	Validation error / Application not found / Application not pending / Vehicle record not found / Vahan details mismatch
VAHAN_DETAILS_EXPIRED	Vahan details have expired or are missing
DOCUMENT_ERROR	Document error
RC_DOCUMENTS_REQUIRED	RC documents are required
TAG_NOT_AVAILABLE	Tag is not available or invalid
VEHICLE_ALREADY_REGISTERED	Vehicle already registered
UNAUTHORIZED	You are not authorized to perform this action
INTERNAL_SERVER_ERROR	Database / Internal error

Uploaded Document Info Object

Parameter	Data Type	Description
extension	String	File extension
doc_type	String - See DocumentType	Document type
redis_key	String	Redis key for the uploaded document

Validate Tag

Pre-validates a tag before creating vehicle record. Used to validate tag is available and valid before DB record creation.

Endpoint: POST /api/v1/fastag/dashboard/customer/applications/fastag/tag/validate

Sample Request - Using TagId:

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/applications/fastag/tag/validate' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "tag_identifier": {
    "tag_id": "1234567890ABCDEF12345678"
  },
  "vehicle_class": "CAR"
}'

Sample Request - Using Barcode:

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/applications/fastag/tag/validate' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "tag_identifier": {
    "barcode": {
      "serial_number": 12345678,
      "issuer_key_index": 1,
      "issuer_iin": 890123
    }
  },
  "vehicle_class": "CAR"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Tag validated successfully",
  "payload": {
    "is_valid": true,
    "tag_id": "1234567890ABCDEF12345678"
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
application_id	String	Application UUID	Yes
tag_identifier	Object	Tag identification (Enum: TagId or Barcode)	Yes
vehicle_class	String - See VehicleClass	Vehicle class	Yes

tag_identifier (Enum - one of the following):

Variant	Parameters	Data Type	Description
Barcode	serial_number	Number	Serial number from barcode
	issuer_key_index	Number	Issuer key index
	issuer_iin	Number	Issuer IIN
TagId	tag_id	String	Direct tag ID (24 or 32 hex characters)

Response Parameters:

Parameter	Data Type	Description
is_valid	Boolean	Whether the tag is valid
tag_id	String	The validated tag ID

Error Codes:

Error Code	Description
BAD_REQUEST	Validation error
FORBIDDEN	CRN not found for customer / Not authorized
TAG_NOT_AVAILABLE	Tag is invalid or not available
INTERNAL_SERVER_ERROR	Database / Internal error

Proof of Fitment

Vehicle Fitment

Fitment details of the tag and the associated vehicle.

Endpoint: POST /api/v1/fastag/dashboard/customer/vehicle/fitment

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/vehicle/fitment' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "vrn": "MH01AB1234"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Success",
  "payload": {
    "vrn": "MH01AB1234",
    "chassis_no": "CHASSIS123456",
    "engine_no": "ENGINE123456",
    "tag_id": "TAG123456",
    "tid": "TID123456",
    "barcode_no": "BARCODE123456",
    "fitment_challan_number": "FC/2024/001",
    "fitment_date": "2024-01-15",
    "fitment_time": "10:30:45",
    "bank_issuer_name": "HDFC Bank"
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
vrn	String	Vehicle Registration Number	Yes

Response Parameters:

Parameter	Data Type	Description
vrn	String	Vehicle Registration Number
chassis_no	String	Vehicle chassis number (VIN)
engine_no	String	Vehicle engine number
tag_id	String	FASTag ID
tid	String	Terminal Identifier (TID)
barcode_no	String	Barcode number
fitment_challan_number	String	Fitment challan number
fitment_date	String	Fitment date (YYYY-MM-DD)
fitment_time	String	Fitment time (HH:MM:SS)
bank_issuer_name	String	Bank issuer name

Error Codes:

Error Code	Description
UNAUTHORIZED	Session invalid or customer not authorized for this vehicle
BAD_REQUEST	Vehicle not found or KYV not complete
INTERNAL_SERVER_ERROR	Failed to get vehicle fitment details

Add Money (Work in Progress)

Eligibility API

Checks whether the customer is eligible to add money to the wallets.

Endpoint: POST /api/v1/fastag/dashboard/customer/payments/recharge/eligibility

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/payments/recharge/eligibility' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "amount": 100.00
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Success",
  "payload": {
    "current_balance": "1500.00",
    "wallet_status": "ACTIVE",
    "rejection_reason": null,
    "is_eligible": true
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
amount	Decimal	Intended recharge amount	Yes

Response Parameters:

Parameter	Data Type	Description
current_balance	Decimal	Current balance amount in the wallet
wallet_status	String	Current status of the wallet. See WalletStatus
rejection_reason	String	Reason for rejection if wallet is rejected; null otherwise
is_eligible	Boolean	Whether the customer is eligible for recharge

Error Codes:

Error Code	Description
CUSTOMER_NOT_FOUND	Customer not found
CUSTOMER_INACTIVE	Customer is inactive
WALLET_NOT_FOUND	Wallet not found
NO_WALLET_CONFIGURED	No wallet configured for customer
INTERNAL_ERROR	Internal server error

Credit Transaction API

Updates the status of a pending transaction (credit/recharge) based on the payment gateway response.

Endpoint: POST /api/v1/fastag/dashboard/kotak/transaction/update

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/kotak/transaction/update' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "transaction_id": "TXN123456789",
  "amount": 100.00,
  "status": "SUCCESS",
  "transaction_initiated_at": "2025-04-28T10:30:00Z",
  "transaction_completed_at": "2025-04-28T10:31:00Z",
  "payment_mode": "UPI",
  "order_id": "ORD123456789",
  "instrument_type": "UPI_INTENT",
  "instrument_id": "user@vpa"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Success",
  "payload": {
    "message": "Transaction updated successfully"
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
crn	String	Customer's CRN	Yes
transaction_id	String	The gateway transaction ID to update	Yes
amount	Decimal	Transaction amount — must be positive with at most 2 decimal places	Yes
status	String	New status. See TransactionCreditStatus	Yes
transaction_initiated_at	String	When the transaction was initiated (ISO 8601 / RFC 3339)	Yes
transaction_completed_at	String	When the transaction completed (ISO 8601 / RFC 3339)	No
order_id	String	Order ID from the payment gateway	Yes
instrument_type	String	Instrument type. See PaymentInstrumentTypeV2	Yes
instrument_id	String	Instrument ID (e.g. UPI VPA)	Yes
credit_source	String	Credit Source. See CreditSource	Yes

Response Parameters:

Parameter	Data Type	Description
message	String	Confirmation message for the transaction update

Error Codes:

Error Code	Description
UNAUTHORIZED	Transaction does not belong to this customer
INTERNAL_SERVER_ERROR	Failed to update transaction
WALLET_ERROR	An internal error occurred. Please try again later.
WALLET_LIMIT_EXCEEDED	Wallet limit exceeded. Available limit is returned in the error message. This transaction is set to FAILURE status
CONFLICT	Transaction already in terminal state
BAD_REQUEST	Invalid request parameters

Vehicle Update APIs (Work in Progress)

Initiate Vehicle Update

Initiates a request to update vehicle information.

Endpoint: POST /api/v1/fastag/dashboard/customer/vehicle-update/initiate

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/vehicle-update/initiate' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "vehicle_id": "VEH_123456",
  "engine_number": "ENGINE123456"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Success",
  "payload": {
    "application_id": "APP_UPDATE_123456",
    "existing_vehicle_details": {
      "vehicle_id": "VEH_123456",
      "vrn": "MH01AB1234",
      "vin": "CHASSIS123456",
      "engine_number": "ENGINE123456",
      "region_state": "Maharashtra",
      "fuel_type": "PETROL",
      "vehicle_class": "VC4",
      "model": "Camry",
      "is_commercial_vehicle": false
    },
    "vahan_details": {
      "vrn": "MH01AB1234",
      "vin": "CHASSIS123456",
      "engine_number": "ENGINE123456",
      "region_state": "Maharashtra",
      "fuel_type": "PETROL",
      "is_national_permit": false,
      "model": "Camry",
      "chassis_number": "CHASSIS123456",
      "national_permit_end_date": null,
      "gvw": "1500",
      "registered_vehicle": null,
      "vehicle_descriptor": null
    },
    "documents": [
      {
        "upload_url": "https://s3-presigned-url",
        "type": "RcF"
      }
    ]
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
vehicle_id	String	Vehicle ID (UUID)	Yes
vrn	String	Vehicle Registration Number	No
vin	String	Vehicle Identification Number	No
engine_number	String	Engine number	Yes

Response Parameters:

Parameter	Data Type	Description
application_id	String	Application ID for the update request
existing_vehicle_details	ExistingVehicleDetails	Current vehicle details from database
vahan_details	VahanDetails	Vahan API response with vehicle details
documents	DocumentUploadInfo[]	List of document upload information

ExistingVehicleDetails Object:

Field	Data Type	Description
vehicle_id	String	Vehicle ID
vrn	String	Current VRN
vin	String	Current VIN
engine_number	String	Current engine number
region_state	String	State of registration
fuel_type	String	Fuel type
vehicle_class	String	Vehicle class
model	String	Vehicle model
is_commercial_vehicle	Boolean	Whether vehicle is commercial

VahanDetails Object:

Field	Data Type	Description
vrn	String	VRN from Vahan
vin	String	VIN from Vahan
engine_number	String	Engine number from Vahan
region_state	String	State of registration from Vahan
fuel_type	String	Fuel type from Vahan
is_national_permit	Boolean	Has national permit
model	String	Vehicle model from Vahan
chassis_number	String	Chassis number from Vahan
national_permit_end_date	String	National permit end date
gvw	String	Gross vehicle weight in kg
registered_vehicle	String	Registerd Vehicle details
vehicle_descriptor	String	Vehicle Descriptor

DocumentUploadInfo Object:

Field	Data Type	Description
upload_url	String	Presigned S3 upload URL
type	Enum	Document type (See DocumentType)

Error Codes:

Error Code	Description
UNAUTHORIZED	Session invalid or customer CRN missing
WALLET_CREDIT_FREEZE	Credit freeze - operation blocked
WALLET_DEBIT_FREEZE	Debit freeze - operation blocked
WALLET_FREEZE	Wallet frozen - operation blocked
WALLET_CLOSED	Wallet closed - operation not allowed
WALLET_INACTIVE	Wallet inactive - operation not allowed
WALLET_NOT_FOUND	Wallet not found
DATABASE_ERROR	Database error during wallet check
VEHICLE_NOT_FOUND	Vehicle not found for the given ID
UNAUTHORIZED	Customer does not own this vehicle
VEHICLE_VALIDATION_FAILED	Vehicle validation failed

Submit Vehicle Update

Submits updated vehicle information.

Endpoint: POST /api/v1/fastag/dashboard/customer/vehicle-update/submit

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/vehicle-update/submit' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "application_id": "APP_UPDATE_123456",
  "vrn": "MH01AB1234",
  "vin": "CHASSIS123456",
  "engine_number": "ENGINE123456",
  "vehicle_class": "VC4",
  "fuel_type": "PETROL",
  "is_commercial": false,
  "has_national_permit": false,
  "national_permit_expiry_date": null,
  "documents": [
    {
      "type": "RcF",
      "extension": "pdf"
    }
  ]
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Success",
  "payload": {
    "id": "APP_UPDATE_123456",
    "status": "Submitted",
    "message": "Vehicle Update Application Submit Successfully"
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
application_id	String	Application ID (UUID)	Yes
vrn	String	Vehicle Registration Number	No
vin	String	Vehicle Identification Number	No
engine_number	String	Engine number	No
vehicle_class	String	Vehicle class	No
fuel_type	String	Fuel type	No
is_commercial	Boolean	Whether vehicle is commercial	No
has_national_permit	Boolean	Has national permit	No
national_permit_expiry_date	String	National permit expiry date	No
documents	RcDocumentInfo[]	List of RC documents	No

RcDocumentInfo Object:

Field	Data Type	Description
type	Enum	Document type (See DocumentType)
extension	String	Doc extention

Response Parameters:

Parameter	Data Type	Description
id	String	Application ID
status	String	Application status
message	String	Success message

Error Codes:

Error Code	Description
UNAUTHORIZED	Session invalid or customer CRN missing, Customer does not own this vehicle
WALLET_CREDIT_FREEZE	Credit freeze - operation blocked
WALLET_DEBIT_FREEZE	Debit freeze - operation blocked
WALLET_FREEZE	Wallet frozen - operation blocked
WALLET_CLOSED	Wallet closed - operation not allowed
WALLET_INACTIVE	Wallet inactive - operation not allowed
WALLET_NOT_FOUND	Wallet not found
DATABASE_ERROR	Database error during wallet check
APPLICATION_NOT_FOUND	Vehicle update application not found
UPDATE_FAILED	Vehicle update failed

List Vehicle Updates

Lists all vehicle update requests for the customer.

Endpoint: POST /api/v1/fastag/dashboard/customer/vehicle-update/list

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/vehicle-update/list' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-12-31T23:59:59Z",
  "page_no": 1,
  "page_size": 10,
  "status": ["Pending", "Submitted"],
  "application_id": null
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Success",
  "payload": {
    "data": [
      {
        "application_id": "APP_UPDATE_123456",
        "application_ref_id": "REF_001",
        "status": "Submitted",
        "customer_seq_id": "100196918",
        "customer_mobile": "9876543210",
        "customer_crn": "100196918",
        "original_vrn": "MH01AB1234",
        "original_vin": "OLD_CHASSIS123",
        "original_engine_number": "OLD_ENGINE123",
        "new_vin": "NEW_CHASSIS456",
        "new_vrn": "MH02CD5678",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "total_count": 1
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
start_time	String	Start time in RFC3339 format	Yes
end_time	String	End time in RFC3339 format	Yes
page_no	Number	Page number (starts from 1)	Yes
page_size	Number	Items per page	Yes
status	Array(Enum)	Filter by status (See VehicleUpdateRequestStatus)	No
application_id	String	Filter by specific application ID	No

Response Parameters:

Parameter	Data Type	Description
data	VehicleUpdateSummaryItem[]	List of vehicle updates
total_count	Number	Total records

VehicleUpdateSummaryItem Object:

Field	Data Type	Description
application_id	String	Application ID
application_ref_id	String	Application reference ID
status	Enum	Status (See VehicleUpdateRequestStatus)
customer_seq_id	String	Customer sequence ID
customer_mobile	String	Customer mobile number
customer_crn	String	Customer CRN
original_vrn	String	Original VRN
original_vin	String	Original VIN
original_engine_number	String	Original engine number
new_vin	String	New VIN
new_vrn	String	New VRN
created_at	String	Created timestamp

Error Codes:

Error Code	Description
UNAUTHORIZED	Session invalid
BAD_REQUEST	Invalid start_time or end_time format
INTERNAL_SERVER_ERROR	Failed to list vehicle updates

Get Vehicle Update Details

Gets detailed information of a specific vehicle update request.

Endpoint: GET /api/v1/fastag/dashboard/customer/vehicle-update/details/{application_id}

curl -L -X GET '{{host}}/api/v1/fastag/dashboard/customer/vehicle-update/details/APP_UPDATE_123456' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Success",
  "payload": {
    "application_id": "APP_UPDATE_123456",
    "application_ref_id": "REF_001",
    "status": "Submitted",
    "customer_seq_id": "CUST_SEQ_001",
    "customer_crn": "100196918",
    "customer_mobile_number": "9876543210",
    "original_vrn": "MH01AB1234",
    "original_vin": "OLD_CHASSIS123",
    "original_engine_number": "OLD_ENGINE123",
    "new_vehicle_details": {
      "vin": "NEW_CHASSIS456",
      "vrn": "MH02CD5678",
      "engine_number": "NEW_ENGINE456"
    },
    "vahan_details": {
      "vrn": "MH02CD5678",
      "chassis_number": "NEW_CHASSIS456",
      "engine_number": "NEW_ENGINE456",
      "model": "Camry",
      "manufacturer": "Toyota"
    },
    "rc_documents": [
      {
        "download_url": "https://s3-presigned-download-url",
        "type": "RcF",
        "extension": "pdf"
      }
    ],
    "old_vehicle_details": {
      "vin": "OLD_CHASSIS123",
      "vrn": "MH01AB1234",
      "engine_number": "OLD_ENGINE123"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Path Parameters:

Parameter	Data Type	Description	Required
application_id	String	Application ID (UUID)	Yes

Response Parameters:

Parameter	Data Type	Description
application_id	String	Application ID
application_ref_id	String	Application reference ID
status	Enum	Status (See VehicleUpdateRequestStatus)
customer_seq_id	String	Customer sequence ID
customer_crn	String	Customer CRN
customer_mobile_number	String	Customer mobile number
original_vrn	String	Original VRN
original_vin	String	Original VIN
original_engine_number	String	Original engine number
new_vehicle_details	Object	New vehicle details
vahan_details	Object	Vahan API response
rc_documents	DocumentDownloadInfo[]	RC documents with download URLs
old_vehicle_details	Object	Old vehicle details
created_at	String	Created timestamp

NewVehicleDetails Object:

Field	Data Type	Description
vrn	String	New VRN
vin	String	New VIN
engine_number	String	New engine number
vehicle_class	String	Vehicle class
fuel_type	String	Fuel type
is_commercial	Boolean	Whether vehicle is commercial
has_national_permit	Boolean	Has national permit
national_permit_expiry_date	String	National permit expiry date

OldVehicleInfo Object:

Field	Data Type	Description
vrn	String	Old VRN
vin	String	Old VIN
engine_number	String	Old engine number
vehicle_class	String	Vehicle class
fuel_type	String	Fuel type
is_commercial	Boolean	Whether vehicle is commercial
has_national_permit	Boolean	Has national permit
national_permit_expiry_date	String	National permit expiry date

VahanDetails Object:

Field	Data Type	Description
vrn	String	VRN from Vahan
vin	String	VIN from Vahan
engine_number	String	Engine number from Vahan
region_state	String	State of registration
fuel_type	String	Fuel type
is_national_permit	Boolean	Has national permit
model	String	Vehicle model
chassis_number	String	Chassis number
national_permit_end_date	String	National permit end date
gvw	String	Gross vehicle weight in kg
registered_vehicle	String	Registered vehicle details
vehicle_descriptor	String	Vehicle descriptor

DocumentDownloadInfo Object:

Field	Data Type	Description
download_url	String	Presigned S3 download URL
type	Enum	Document type (See DocumentType)
extension	String	File extension

Error Codes:

Error Code	Description
UNAUTHORIZED	Session invalid, Customer does not own this vehicle
APPLICATION_NOT_FOUND	Vehicle update application not found
INTERNAL_SERVER_ERROR	Failed to get vehicle update details
FORBIDDEN	You do not have access to this application

Transaction APIs

Transaction Statement

Generates a comprehensive transaction statement for the customer.

Endpoint: POST /api/v1/fastag/dashboard/customer/transaction/statement

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/transaction/statement' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "vrn": "MH12AB1234",
  "start_time": "2024-04-01T00:00:00Z",
  "end_time": "2024-04-30T23:59:59Z",
  "format": "RAW"
}'

# Response: 200 OK
# Response: 200 OK
{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Success",
  "payload": {
    "customer_statement_details": {
      "customer_details": {
        "customer_id": "CUST123456",
        "crn": "100196918",
        "mobile_number": "9876543210",
        "customer_name": "John Doe",
        "kyc_status": "FKYC",
        "email_address": "john.doe@example.com",
        "delivery_address": "123 Main Street, Mumbai",
        "total_active_tags": 2
      },
      "statement_date_time": "2025-04-28T18:00:00Z",
      "statement_period": "2025-01-01 to 2025-04-28",
      "total_vehicle": 2,
      "wallet_opening_balance": "1000.00",
      "wallet_closing_balance": "2500.00",
      "master_opening_balance": "5000.00",
      "master_closing_balance": "4800.00",
      "master_account_number": "1234567890",
      "gstn_no": "27AABCU9603R1ZM",
      "security_deposit": "200.00"
    },
    "vehicle_summary": [
      {
        "vehicle_number": "MH12AB1234",
        "serial_no": "1",
        "barcode": "BAR123456",
        "tag_id": "TAG123456789",
        "vehicle_class": "VC4",
        "commercial_flag": "YES",
        "trip_count": 45,
        "txn_amount": "4500.00",
        "group_name": "Fleet A"
      }
    ],
    "master_account_details": [
      {
        "transaction_date_and_time": "2025-04-28T10:30:00Z",
        "processing_date_and_time": "2025-04-28T10:35:00Z",
        "unique_transaction_id": "TXN123456789",
        "transaction_type": "DEBIT",
        "transaction_description": "Toll deduction at Mumbai Plaza",
        "account_number": "1234567890",
        "debit_amt": "200.00",
        "credit_amt": null,
        "opening_balance": "5000.00",
        "closing_balance": "4800.00"
      }
    ],
    "wallet_transaction_details": [
      {
        "transaction_date_and_time": "2025-04-28T10:30:00Z",
        "processing_date_and_time": "2025-04-28T10:35:00Z",
        "unique_transaction_id": "TXN123456789",
        "transaction_type": "DEBIT",
        "transaction_description": "Toll deduction at Mumbai Plaza",
        "debit_amt": "200.00",
        "credit_amt": null,
        "opening_balance": "1500.00",
        "closing_balance": "1300.00",
        "plaza_code": "MUM001",
        "plaza_name": "Mumbai Plaza",
        "lane_id": "L1",
        "transaction_date": "2025-04-28",
        "trip_number": "TRIP123",
        "vrn_or_vin": "MH12AB1234",
        "tag_id": "TAG123456789",
        "tag_serial_number": "TSN123456",
        "group_name": "Fleet A"
      }
    ],
    "payment_to_kotak_bank": [
      {
        "transaction_date_and_time": "2025-04-28T10:30:00Z",
        "unique_transaction_id": "TXN123456789",
        "transaction_description": "Toll payment",
        "hsn_code": "996311",
        "vehicle_number": "MH12AB1234",
        "tag_id": "TAG123456789",
        "serial_no": "1",
        "transaction_amount": "200.00",
        "sgst": "9.00",
        "igst": "0.00",
        "cgst": "9.00",
        "grand_total": "218.00"
      }
    ]
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
vrn	String	Vehicle Registration Number to filter	No
start_time	String	Start time in RFC3339 format	Yes
end_time	String	End time in RFC3339 format	Yes
format	String	Statement format (e.g., RAW)	No

Response Parameters:

Parameter	Data Type	Description
customer_statement_details	Object(Customer Statement Details Object)	Customer and statement summary information
vehicle_summary	Array(Vehicle Summary Object)	Summary of each vehicle's transactions
master_account_details	Array(Master Account Details Object)	Master wallet transaction details
wallet_transaction_details	Array(Wallet Transaction Details Object)	PPI wallet transaction details
payment_to_kotak_bank	Array(Payment To Kotak Bank Object)	Tax breakdown for payments

Customer Statement Details Object

Parameter	Data Type	Description
customer_details	Object(Report Customer Details Object)	Customer identification and contact details
statement_date_time	String	Timestamp when statement was generated
statement_period	String	Date range of the statement
total_vehicle	Number	Total number of vehicles
wallet_opening_balance	Decimal	PPI wallet opening balance
wallet_closing_balance	Decimal	PPI wallet closing balance
master_opening_balance	Decimal	Master wallet opening balance
master_closing_balance	Decimal	Master wallet closing balance
master_account_number	String	Master account number
gstn_no	String	GSTIN number of Kotak Bank
security_deposit	Decimal	Total security deposit

Report Customer Details Object

Parameter	Data Type	Description
customer_id	String	Unique customer identifier
crn	String	Customer Reference Number
mobile_number	String	Customer's mobile number
customer_name	String	Full name of the customer
kyc_status	String	KYC verification status (LKYC, FKYC)
email_address	String	Customer's email address
delivery_address	String	Customer's delivery address
total_active_tags	Number	Number of active FASTag tags

Vehicle Summary Object

Parameter	Data Type	Description
vehicle_number	String	Vehicle registration number
serial_no	String	Serial number
barcode	String	FASTag barcode
tag_id	String	FASTag ID
vehicle_class	String	Vehicle classification
commercial_flag	String	Commercial vehicle indicator
trip_count	Number	Total number of trips
txn_amount	Decimal	Total transaction amount
group_name	String	Vehicle group name

Master Account Details Object

Parameter	Data Type	Description
transaction_date_and_time	String	Transaction timestamp
processing_date_and_time	String	Processing timestamp
unique_transaction_id	String	Unique transaction identifier
transaction_type	String	Type. See See DbTransactionType
transaction_description	String	Transaction description
account_number	String	Account number
debit_amt	Decimal	Debit amount
credit_amt	Decimal	Credit amount
opening_balance	Decimal	Opening balance
closing_balance	Decimal	Closing balance

Wallet Transaction Details Object

Parameter	Data Type	Description
transaction_date_and_time	String	Transaction timestamp
processing_date_and_time	String	Processing timestamp
unique_transaction_id	String	Unique transaction identifier
transaction_type	String	Type. See DbTransactionType
transaction_description	String	Transaction description
debit_amt	Decimal	Debit amount
credit_amt	Decimal	Credit amount
opening_balance	Decimal	Opening balance
closing_balance	Decimal	Closing balance
plaza_code	String	Toll plaza code
plaza_name	String	Toll plaza name
lane_id	String	Lane identifier
transaction_date	String	Transaction date
trip_number	String	Trip identifier
vrn_or_vin	String	Vehicle registration or VIN
tag_id	String	FASTag ID
tag_serial_number	String	FASTag serial number
group_name	String	Transaction group name

Payment To Kotak Bank Object

Parameter	Data Type	Description
transaction_date_and_time	String	Transaction timestamp
unique_transaction_id	String	Unique transaction identifier
transaction_description	String	Transaction description
hsn_code	String	HSN code for GST
vehicle_number	String	Vehicle registration number
tag_id	String	FASTag ID
serial_no	String	Serial number
transaction_amount	Decimal	Base transaction amount
sgst	Decimal	State GST
igst	Decimal	Integrated GST
cgst	Decimal	Central GST
grand_total	Decimal	Total amount including tax

Error Codes:

Error Code	Description
BAD_REQUEST	Customer not registered
INTERNAL_SERVER_ERROR	Failed to generate statement

Application Transactions List

Lists transactions for a specific FASTag application.

Endpoint: POST /api/v1/fastag/dashboard/customer/applications/transactions/list

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/applications/transactions/list' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "application_id": "APP_123456"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Request Success",
  "payload": {
    "transactions": [
      {
        "txn_status": "SUCCESS",
        "txn_id": "TXN_123456",
        "transactions_ref_id": "REF_789",
        "txn_mode": "PG"
      }
    ]
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
application_id	String	Application ID (UUID)	Yes

Response Parameters:

Parameter	Data Type	Description
transactions	ApplicationTransaction[]	List of application transactions

ApplicationTransaction Object:

Field	Data Type	Description
txn_status	Enum	Transaction status (See DbTransactionStatus)
txn_id	String	Transaction ID
transactions_ref_id	String	Reference ID
txn_mode	String	Transaction mode (e.g., PG, WALLET)
txn_timestamp	String	Transaction timestamp
order_id	String	Order ID
txn_amount	Number	Transaction amount

Error Codes:

Error Code	Description
BAD_REQUEST	Invalid application ID format, application not found, validation error, or internal server error
UNAUTHORIZED	Not authorized to view this application

Auto-Recharge APIs (Work in Progress)

Get Auto-Recharge Config

Gets the customer's auto-recharge configuration.

Endpoint: GET /api/v1/fastag/dashboard/customer/auto-recharge/config

curl -L -X GET '{{host}}/api/v1/fastag/dashboard/customer/auto-recharge/config' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \

# Response: 200 OK
{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Auto-recharge config retrieved successfully",
  "payload": {
    "is_enabled": false,
    "instrument_type": "SBA",
    "instrument_id": "ACC1234567890",
    "instrument_display_value": "XXXX-7890",
    "recharge_amount": 500.00,
    "threshold_amount": 200.00,
    "min_recharge": 100.00,
    "max_recharge_casa": 10000.00,
    "max_recharge_cc": 25000.00,
    "min_threshold": 100.00
  }
}

Response Parameters:

Parameter	Data Type	Description
is_enabled	Boolean	Whether auto-recharge is currently enabled
instrument_type	String	Instrument type (CC, SBA, CAA, or PG). See PaymentInstrumentTypeV2 - only if configured
instrument_id	String	Instrument ID (account number or card number) - only if configured
instrument_display_value	String	Instrument display value (e.g., "XXXX-1234") - only if configured
recharge_amount	Number	Current recharge amount - only if configured
threshold_amount	Number	Current threshold amount - only if configured
min_recharge	Number	Minimum recharge amount (hard limit based on customer context)
max_recharge_casa	Number	Maximum recharge amount for CASA/OD/Prepaid (SBA, CAA, PG) - hard limit
max_recharge_cc	Number	Maximum recharge amount for Credit Card (CC) - hard limit
min_threshold	Number	Minimum threshold amount (hard limit based on customer context)

Error Codes:

Error Code	Description
UNAUTHORIZED	Your session isn't valid, please try logging again
CUSTOMER_NOT_FOUND	Customer not found
DATABASE_ERROR	Failed to fetch customer details
INTERNAL_ERROR	Failed to get auto-recharge settings
WALLET_NOT_FOUND	Wallet not found
WALLET_CLOSED	Wallet is closed
WALLET_INACTIVE	Wallet is inactive
WALLET_CREDIT_FREEZE	Wallet is credit-frozen
WALLET_DEBIT_FREEZE	Wallet is debit-frozen
WALLET_FREEZE	Wallet is completely frozen

Initiate Auto-Recharge

Generates an OTP to enable/modify auto-recharge.

Endpoint: POST /api/v1/fastag/dashboard/customer/auto-recharge/initiate

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/auto-recharge/initiate' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "operation": "enable",
  "instrumentId": "ACC1234567890",
  "rechargeAmount": 500.00,
  "thresholdAmount": 200.00
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Auto-recharge OTP generated successfully",
  "payload": {
    "otpReferenceId": "OTP_REF_123456",
    "expiresAt": "2024-01-15T10:30:00Z",
    "remainingResendCount": 3
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
operation	String	Operation type: enable, modify, or disable. See AutoRechargeOperation	Yes
instrumentId	String	Instrument ID (account number or card number).	Yes (for enable/modify)
rechargeAmount	Number	Recharge amount to be debited	Yes (for enable/modify)
thresholdAmount	Number	Threshold amount that triggers auto-recharge	Yes (for enable/modify)

Response Parameters:

Parameter	Data Type	Description
otpReferenceId	String	OTP reference ID for subsequent validation
expiresAt	String	OTP expiry timestamp (ISO 8601)
remainingResendCount	Integer	Remaining OTP resend attempts

Error Codes:

Error Code	Description
UNAUTHORIZED	Your session isn't valid, please try logging again
WALLET_NOT_FOUND	Wallet not found
WALLET_CLOSED	Wallet is closed
WALLET_INACTIVE	Wallet is inactive
WALLET_CREDIT_FREEZE	Wallet is credit-frozen
WALLET_DEBIT_FREEZE	Wallet is debit-frozen
WALLET_FREEZE	Wallet is completely frozen
CONFLICT	OTP already active - please wait for expiry
BAD_REQUEST	OTP generation failed or other client errors
INTERNAL_SERVER_ERROR	Internal server error

Submit Auto-Recharge

Validates OTP and enables/modifies auto-recharge.

Endpoint: POST /api/v1/fastag/dashboard/customer/auto-recharge/submit

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/auto-recharge/submit' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "otp": "123456",
  "eligibilityToken": "OTP_REF_123456"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Auto-recharge enabled successfully",
  "payload": {
    "success": true,
    "message": "Auto-recharge enabled successfully",
    "operation": "enable",
    "autoRechargeId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
otp	String	OTP value	Yes
eligibilityToken	String	OTP reference ID from generate-otp step	Yes

Response Parameters:

Parameter	Data Type	Description
success	Boolean	Whether the operation was successful
message	String	Response message
operation	String	The operation that was performed. See AutoRechargeOperation
autoRechargeId	String	Auto-recharge ID (if successfully created/updated)
remainingValidationCount	Integer	Remaining OTP validation attempts (only when OTP validation fails)

Error Codes:

Error Code	Description
UNAUTHORIZED	Your session isn't valid, please try logging again
WALLET_NOT_FOUND	Wallet not found
WALLET_CLOSED	Wallet is closed
WALLET_INACTIVE	Wallet is inactive
WALLET_CREDIT_FREEZE	Wallet is credit-frozen
WALLET_DEBIT_FREEZE	Wallet is debit-frozen
WALLET_FREEZE	Wallet is completely frozen
BAD_REQUEST	OTP validation failed or other client errors
CONFLICT	OTP already active - please wait for expiry
INTERNAL_SERVER_ERROR	Internal server error

Complaint APIs

Complaint Configuration

Gets the complaint configuration settings.

Endpoint: GET /api/v1/fastag/dashboard/customer/complaints/configuration

curl -L -X GET '{{host}}/api/v1/fastag/dashboard/customer/complaints/configuration' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \

# Response: 200 OK
{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Complaint configuration retrieved successfully",
  "payload": {
    "complaints": [
      {
        "display_name": "Tag Not Working",
        "complaint_configuration_id": "550e8400-e29b-41d4-a716-446655440000",
        "is_txn_mandatory": true,
        "is_full_partial_allowed": false,
        "types": [
          {
            "display_name": "Tag Not Read",
            "complaint_configuration_id": "660e8400-e29b-41d4-a716-446655440001",
            "documents_required": ["Image"],
            "is_txn_mandatory": true,
            "reason_code": "TAG_NOT_READ"
          }
        ]
      }
    ]
  }
}

Response Parameters:

Parameter	Data Type	Description
complaints	Array(Complaint Type Object)	List of complaint types with nested subtypes.

Complaint Type Object

Parameter	Data Type	Description
display_name	String	Display name of the complaint type
complaint_configuration_id	UUID	Unique identifier for the complaint configuration
is_txn_mandatory	Boolean	Whether transaction is mandatory for this complaint type
is_full_partial_allowed	Boolean	Whether full/partial refund is allowed
txn_filter	Array(Txn Filter Object)	Transaction filter criteria.
types	Array(Complaint Subtype Object)	List of complaint subtypes.

Complaint Subtype Object

Parameter	Data Type	Description
display_name	String	Display name of the complaint subtype
complaint_configuration_id	UUID	Unique identifier for the complaint configuration
documents_required	Array(Complaint Configuration Document Object)	List of required documents.
is_txn_mandatory	Boolean	Whether transaction is mandatory for this subtype
is_full_partial_allowed	Boolean	Whether full/partial refund is allowed
txn_filter	Array(Txn Filter Object)	Transaction filter criteria.
reason_code	String	Reason code for the complaint

Complaint Configuration Document Object

Parameter	Data Type	Description
file_name	String	File name of the required document
display_name	String	Display name of the document
is_mandatory	Boolean	Whether the document is mandatory

Txn Filter Object

Parameter	Data Type	Description
sources	Array	List of transaction sources
transaction_types	Array	List of transaction types

Error Codes:

Error Code	Description
INTERNAL_SERVER_ERROR	Failed to fetch complaint configurations

Raise Complaint

Raises a new complaint.

Endpoint: POST /api/v1/fastag/dashboard/customer/complaints/raise

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/complaints/raise' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "complaint_configuration_id": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Transaction not reflected",
  "transaction_id": "660e8400-e29b-41d4-a716-446655440001",
  "email": "user@example.com",
  "amount": "100.00"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Complaint raised successfully",
  "payload": {
    "complaint_id": "550e8400-e29b-41d4-a716-446655440000",
    "complaint_ref_id": "COMP_123456",
    "status": "PENDING",
    "documents": [
      {
        "file_name": "receipt.jpg",
        "display_name": "Receipt",
        "upload_url": "complaint/upload-path/file-name"
      }
    ]
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
complaint_configuration_id	String	Complaint configuration ID from configuration endpoint	Yes
description	String	Complaint description	Yes
transaction_id	String	Transaction ID (optional)	No
email	String	Email address (optional)	No
amount	String	Dispute amount (optional)	No

Response Parameters:

Parameter	Data Type	Description
complaint_id	UUID	Created complaint ID
complaint_ref_id	String	Complaint reference ID
status	String	Complaint status. See ComplaintStatus
documents	Array(Complaint Document Upload Object)	List of documents to upload.

Complaint Document Upload Object

Parameter	Data Type	Description
file_name	String	File name of the document
display_name	String	Display name of the document
upload_path	String	Path for uploading the document

Error Codes:

Error Code	Description
BAD_REQUEST	Customer ID not found in session or invalid dispute amount
CONFLICT	Complaint already raised for this transaction
NOT_FOUND	Transaction not found, complaint configuration not found, or customer not found
INTERNAL_SERVER_ERROR	Failed to raise complaint

Submit Complaint

Submits a complaint for processing after uploading required documents.

Endpoint: POST /api/v1/fastag/dashboard/customer/complaints/submit

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/complaints/submit' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "complaint_id": "550e8400-e29b-41d4-a716-446655440000",
  "documents_uploaded": [
    {
      "file_name": "receipt.jpg",
      "extension": "jpg"
    }
  ]
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Complaint submitted successfully",
  "payload": {
    "complaint_id": "550e8400-e29b-41d4-a716-446655440000",
    "complaint_ref_id": "COMP_123456",
    "status": "SUBMITTED"
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
complaint_id	UUID	Complaint ID to submit	Yes
documents_uploaded	Array(Uploaded Document Object)	List of uploaded documents.	Yes

Response Parameters:

Parameter	Data Type	Description
complaint_id	UUID	Submitted complaint ID
complaint_ref_id	String	Complaint reference ID
status	String	Complaint status. See ComplaintStatus

Uploaded Document Object

Parameter	Data Type	Description
file_name	String	File name of the uploaded document
extension	String	File extension (e.g., jpg, pdf)

Error Codes:

Error Code	Description
BAD_REQUEST	Customer not registered, complaint not in pending status, or documents not provided
NOT_FOUND	Complaint not found for the given ID
FORBIDDEN	You are not authorized to submit this complaint
INTERNAL_SERVER_ERROR	Failed to process request

List Complaints

Lists all complaints for the customer.

Endpoint: POST /api/v1/fastag/dashboard/customer/complaints/list

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/complaints/list' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "start_date": "2024-01-01T00:00:00Z",
  "end_date": "2024-02-01T00:00:00Z",
  "page_no": 1,
  "page_size": 10
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Complaints retrieved successfully",
  "payload": {
    "complaints": [],
    "total_count": 0,
    "page_no": 1,
    "page_size": 10
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
start_date	String	Start date in RFC3339 format	Yes
end_date	String	End date in RFC3339 format	Yes
status	Array(String)	Filter by complaint status. See ComplaintStatus	No
page_no	Number	Page number (must be >= 1)	Yes
page_size	Number	Items per page	Yes

Response Parameters:

Parameter	Data Type	Description
complaints	Array	List of complaints
total_count	Number	Total number of complaint records
page_no	Number	Current page number
page_size	Number	Items per page

Error Codes:

Error Code	Description
BAD_REQUEST	Customer not registered or validation error
INTERNAL_SERVER_ERROR	Failed to list complaints

Complaint Details

Gets details of a specific complaint.

Endpoint: POST /api/v1/fastag/dashboard/customer/complaints/details

curl -L -X POST '{{host}}/api/v1/fastag/dashboard/customer/complaints/details' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-client-source: 811' \
-H 'x-customer-crn: 100196918' \
-H 'Authorization: Bearer <session_token>' \
--data-raw '{
  "complaint_id": "550e8400-e29b-41d4-a716-446655440000"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "response_code": "00",
  "response_message": "Complaint details retrieved successfully",
  "payload": {
    "complaint_id": "550e8400-e29b-41d4-a716-446655440000",
    "complaint_ref_id": "COMP_123456",
    "customer_info": {
      "customer_name": "John Doe",
      "mobile_number": "9876543210",
      "email": "john@example.com",
      "customer_ref_id": "100196918",
      "customer_seq_id": "CUST_001"
    },
    "complaint_type_id": "660e8400-e29b-41d4-a716-446655440001",
    "complaint_type_display_name": "Transaction Issue",
    "complaint_subtype_id": "770e8400-e29b-41d4-a716-446655440002",
    "complaint_subtype_display_name": "Amount Deducted Twice",
    "status": "PENDING",
    "description": "Transaction not reflected",
    "vehicle_info": {
      "vin": "VIN123456789",
      "vrn": "ABC123",
      "vehicle_class": "Class 4",
      "fuel_type": "Diesel",
      "is_commercial": "true",
      "national_permit": true,
      "national_permit_expiry": "2025-12-31",
      "tag_issued_date": "2024-01-01"
    },
    "transaction_info": {
      "transaction_id": "880e8400-e29b-41d4-a716-446655440003",
      "gateway_transaction_id": "GTW_123456",
      "transaction_time": "2024-01-15T10:30:00Z",
      "transaction_processing_time": "2024-01-15T10:30:05Z",
      "orig_txn_amount": "500.00",
      "disputed_amount": "500.00",
      "status": "SUCCESS",
      "txn_type": "TOLL",
      "txn_subtype": "PASS"
    },
    "documents": [
      {
        "file_name": "receipt.jpg",
        "display_name": "Receipt",
        "extension": "jpg",
        "document_uri": "https://s3 bucket URL",
        "uploaded_at": "2024-01-15T10:30:00Z"
      }
    ],
    "raised_at": "2024-01-15T10:30:00Z",
    "email": "john@example.com",
    "reason_code": "RC001",
    "review_remarks": "Under review",
    "dispute_amount_type": "FULL"
  }
}

Request Parameters:

Parameter	Data Type	Description	Required
complaint_id	UUID	Complaint ID	Yes

Response Parameters:

Parameter	Data Type	Description
complaint_id	UUID	Complaint ID
complaint_ref_id	String	Complaint reference ID
customer_info	Object(Customer Info Object)	Customer information.
complaint_type_id	UUID	Complaint type configuration ID
complaint_type_display_name	String	Complaint type display name
complaint_subtype_id	UUID	Complaint subtype configuration ID
complaint_subtype_display_name	String	Complaint subtype display name
status	String	Complaint status. See ComplaintStatus
description	String	Complaint description
vehicle_info	Object(Vehicle Info Object)	Vehicle information.
maker	String	Maker details (SELF or OPS)
transaction_info	Object(Transaction Info Object)	Transaction information.
documents	Array(Complaint Document Info Object)	List of documents.
raised_at	String	Complaint raised timestamp
email	String	Customer email
reason_code	String	Reason code (if available)
review_remarks	String	Review remarks (if reviewed)
dispute_amount_type	String	Dispute amount type. See DisputeAmountType

Error Codes:

Error Code	Description
BAD_REQUEST	Customer not registered
NOT_FOUND	Complaint not found for the given ID
FORBIDDEN	You are not authorized to view this complaint
INTERNAL_SERVER_ERROR	Failed to process request

Customer Info Object

Parameter	Data Type	Description
customer_name	String	Customer name
mobile_number	String	Mobile number
email	String	Email address
customer_ref_id	String	Customer reference ID
customer_seq_id	String	Customer sequence ID

Vehicle Info Object

Parameter	Data Type	Description
vin	String	Vehicle Identification Number
vrn	String	Vehicle registration number
vehicle_class	String	Vehicle class
fuel_type	String	Fuel type
is_commercial	String	Whether vehicle is commercial ("true" or "false")
national_permit	Boolean	National permit status
national_permit_expiry	String	National permit expiry date
tag_issued_date	String	Tag issued date

Transaction Info Object

Parameter	Data Type	Description
transaction_id	UUID	Transaction ID
gateway_transaction_id	String	Gateway transaction ID
transaction_time	String	Transaction timestamp
transaction_processing_time	String	Transaction processing time
orig_txn_amount	String	Original transaction amount
disputed_amount	String	Disputed amount
status	String	Transaction status
txn_type	String	Transaction type
txn_subtype	String	Transaction subtype

Complaint Document Info Object

Parameter	Data Type	Description
file_name	String	File name
display_name	String	Display name
extension	String	File extension
document_uri	String	Document URL
uploaded_at	String	Upload timestamp

Enums

FastagTransactionSource

Value	Description
NETC	NETC toll/parking transactions
FASTAG_AUTO_TOPUP	Automatic wallet top-up
FASTAG_WALLET_RECHARGE	Manual wallet recharge
REGISTRATION	Tag registration transactions
UNREGISTERED_TAG_TXN	Transactions for unregistered tags
FASTAG_APPLICATION_REJECTION	Application rejection refunds
WALLET_AUTO_RECHARGE	Auto-recharge transactions
APPLICATION_FEE	Application fee deductions
FASTAG_CLOSURE_REFUND	Tag closure refunds
BBPS	BBPS payment transactions
UPI	UPI payment transactions
TAG_REPLACEMENT_FEE	Tag replacement fees
TAG_REPLACEMENT_REJECTION_REFUND	Tag replacement rejection refunds

CreditSource

Value	Description
Recharge	Credit Source for recording a Recharge to customer's wallet

DbTransactionType

Value	Description
CR	Credit transaction
DR	Debit transaction
NON_FIN	Non-financial transaction

DbTransactionStatus

Value	Description
PENDING	Transaction pending
SUCCESS	Transaction successful
FAILURE	Transaction failed

FastagStatus

Value	Description
ACTIVE	Tag is active and usable
CLOSED	Tag has been closed

ExceptionSource

Value	Description
BANK	Exception added by bank
CUSTOMER	Exception requested by customer
SWITCH	Exception from NPCI switch
WALLET	Exception from wallet system
TAG_CLOSURE	Exception due to tag closure
WALLET_FREEZE	Exception due to wallet freeze

ExceptionCodeStatus

Value	Description
ACTIVE	Exception is currently active
INACTIVE	Exception has been removed

VehicleClass

Value	Description
VC1	Car/Jeep/Van
VC2	Light Commercial Vehicle (LCV)
VC3	Bus (2 axle)
VC4	Bus (3 axle)
VC5	Truck (2 axle)
VC6	Truck (3 axle)
VC7	Truck (4 axle)
VC8	Truck (5 axle)
VC9	Truck (6 axle)
VC10	Earth Moving Equipment
VC11	Heavy Construction Equipment
VC12	Tractor
VC13	Trailer (3 axle)
VC14	Trailer (4 axle)
VC15	Trailer (5 axle)
VC16	Trailer (6 axle)
VC17	Trailer (7 axle)
VC18	Trailer (8 axle)
VC19	Trailer (9 axle)
VC20	Multi-axle vehicle

WalletStatus

Value	Description
ACTIVE	Wallet is active
INACTIVE	Wallet is inactive
CLOSED	Wallet has been closed
CREDIT_FREEZE	Wallet is frozen for credit
DEBIT_FREEZE	Wallet is frozen for debit
FREEZE	Wallet is completely frozen

WalletType

Value	Description
MASTER	Master wallet
PPI	Prepaid Instrument wallet
FASTAG_SECURITY	Fastag security deposit wallet

ApplicationChannel

Value	Description
WEB_PORTAL	Web portal channel
BANK_PORTAL	Bank portal channel
CUSTOMER_PORTAL	Customer portal channel
MB_811_APP	Mobile app 811 channel

FastagChannel

Value	Description
DEFAULT	Default channel
Other	Custom channel name (string value)

FastagApplicationStatus

Value	Description
PENDING	Application is pending
PAYMENT_PENDING	Payment is pending
PAYMENT_INITIATED	Payment has been initiated
PAYMENT_FAILED	Payment has failed
SUBMITTED	Application has been submitted
CLOSED	Application has been closed

FastagAppInfoStatus

Value	Description
SUBMITTED	Vehicle info submitted
APPROVED	Vehicle info approved
REJECTED	Vehicle info rejected
REGISTERED	Vehicle info registered
PENDING	Vehicle info pending
HOLD	Vehicle info on hold
PENDING_TAG_DETAILS	Tag details pending

DocumentStatus

Value	Description
PENDING	Document pending verification
APPROVED	Document approved
REJECTED	Document rejected

DocumentType

Value	Description
KYV_FR	KYV Front document
KYV_S	KYV Side document
KYV_TG	KYV Tag document
VHC	Vehicle document
MA	Manufacturer document
RC_F	RC Front document
RC_B	RC Back document
CHQ	Cheque document
WALLET_CLOSURE_IMMEDIATE_PROOF	Wallet closure immediate proof document
MISC	Miscellaneous document

OrderBy

Value	Description
asc	Ascending order
desc	Descending order

KyvApplicationStatus

Value	Description
PENDING	KYV application pending
SUBMITTED	KYV application submitted
APPROVED	KYV application approved
REJECTED	KYV application rejected
HOLD	KYV application on hold

ClosureStatus

Value	Description
SUBMITTED	Closure request submitted
APPROVED	Closure request approved
REJECTED	Closure request rejected
PENDING	Closure request pending

FastagClosureInitiatedBy

Value	Description
CUSTOMER	Initiated by customer
NETC	Initiated by NETC
BANK	Initiated by bank

FastagWalletType

Value	Description
MASTER	Master wallet for a customer
PPI	Prepaid Payment Instrument wallet for Fastag transactions
FASTAG_SECURITY	Wallet for holding security deposit for a Fastag

FastagClosureEligibilityFailureReason

Tagged enum (discriminated by type field). Possible types:

Type	Additional Fields	Description
TagNotFound	—	Tag not found in database
TagNotFoundInNetc	—	Tag not found in NETC response
TagInException	exception_codes: Array(Closure Exception Code Detail Object)	Tag has exception codes preventing closure
TagAlreadyClosed	—	Tag is already in CLOSED status
ClosureAlreadyRaised	closure_status: See ClosureStatus, closure_id: String	Closure request already exists
NetcError	message: String	Error occurred while fetching data from NETC

SubmitFastagClosureError

Value	Description
DBError	Database error
EligibilityError	Eligibility check failed
FastagNotFound	Fastag not found
VehicleNotFound	Vehicle not found
RequestAlreadyRaised	Closure request already raised
RequestLimitExceeded	Breached max closure request limit
SubmissionPending	Submission is in pending state
NetcCallFailure	NETC call failed
SubmissionError	Submission error
RequestNotFound	Request not found
CustomerNotFound	Customer not found

ReplacementStatus

Value	Description
PENDING	Replacement application pending
SUBMIT	Replacement submitted
APPROVE	Replacement approved
REJECT	Replacement rejected

ReplacementInitiatedBy

Value	Description
CUSTOMER	Replacement initiated by customer
BANK	Replacement initiated by bank
OPS	Replacement initiated by operations

ReplacementReason

Value	Description
DAMAGED	Tag is damaged
LOST	Tag is lost
THEFT	Tag is stolen
DEFECTIVE	Tag is defective
TAG_NOT_WORKING	Tag is not working
CLASS_CHANGE	Vehicle class changed
OTHERS	Other reasons

ReplacementStage

Value	Description
LOW_BALANCE_EXC_INITIATED	Low balance exception initiated
UNDER_REVIEW	Replacement under review
TAG_REPLACEMENT_REJECTED	Tag replacement rejected
TAG_CLOSE_INITIATED	Tag close initiated
TAG_REG_INITIATED	Tag registration initiated
TAG_REGISTERED	Tag registered

RefundStatus

Value	Description
INITIATED	Refund initiated
SUCCESS	Refund successful
FAILURE	Refund failed

PaymentInstrumentTypeV2

Value	Description
CC	Credit Card
SBA	Savings Bank Account
CAA	Current Account
PG	Payment Gateway

TransactionCreditStatus

Value	Description
Pending	Transaction is pending
Success	Transaction completed successfully
Failed	Transaction failed

WalletRechargeStatus

Value	Description
INITIATED	Recharge initiated
SUCCESS	Recharge successful
FAILED	Recharge failed

AutoRechargeOperation

Value	Description
enable	Enable a new auto-recharge
modify	Modify an existing auto-recharge
disable	Disable an existing auto-recharge

ComplaintStatus

Value	Description
PENDING	Complaint is pending
SUBMITTED	Complaint submitted
APPROVED	Complaint approved
REJECTED	Complaint rejected

DisputeAmountType

Value	Description
FULL	Full dispute amount
PARTIAL	Partial dispute amount

ConfigType

Value	Description
MasterConfig	Master configuration type

VehicleUpdateRequestStatus

Value	Description
PENDING	Vehicle update request is pending
SUBMITTED	Vehicle update request is submitted
APPROVED	Vehicle update request is approved
REJECTED	Vehicle update request is rejected

Changelog

May 4, 2026

• Added mobile_number in the request parameters of applications/create API