Challan Payment Status Check
Challan Payment Status
Introduction
This service returns the current state of a challan payment using the requestId returned by the Initiate Challan Payment API. Poll it until the payment reaches a terminal status. Once PAID, the response carries the paymentReceipt link.
Payment lifecycle statuses
Status | Meaning | Terminal |
|---|---|---|
INITIATED | Payment record created | No |
HOLD_PLACED | Amount reserved from your wallet | No |
PROCESSING | Submitted for settlement with the authority | No |
PAID | Settled — receipt available | Yes |
FAILED | Not settled — the reserved amount was released back to your wallet | Yes |
REFUND_INITIATED | A settled payment is being reversed | No |
REFUNDED | Reversal complete — amount credited back to your wallet | Yes |
Online challans usually settle within 1–2 days. Offline challans can take 7–8 working days at the authority.
How to call the API
You are required to pass your assigned access token as the Authorization header in the request. The endpoint is a POST with a JSON body.
Every successful response is wrapped in a result object. Every error is wrapped in an error object with a machine-readable reason and a human-readable message.
API Input Guidelines
- requestId is the mandatory parameter — the id returned by Initiate Challan Payment.
- forceRefresh is optional and defaults to false. When true, the service performs a live sync with the settlement network before responding instead of returning the last known state. This is slower (up to ~30 seconds) — use it sparingly (for example, for a payment that has been PROCESSING unusually long), not on every poll.
- A sensible polling cadence is every few minutes with forceRefresh: false.
- You can only query payments created by your own account — any other requestId returns 404.
Sample Curl
Preproduction
curl --location 'https://api-preproduction.signzy.app/api/v3/challan/payment-status-fetch' \
--header 'Content-Type: application/json' \
--header 'Authorization: <Auth Token>' \
--data '{
"requestId": "8efee8d1-fac1-4906-aede-a3f090dbbcf8",
"forceRefresh": false
}'Production
curl --location 'https://api.signzy.app/api/v3/challan/payment-status-fetch' \
--header 'Content-Type: application/json' \
--header 'Authorization: <Auth Token>' \
--data '{
"requestId": "8efee8d1-fac1-4906-aede-a3f090dbbcf8",
"forceRefresh": false
}'Input Parameters
Parameter | Description | Required |
|---|---|---|
requestId | The payment reference returned by Initiate Challan Payment | Yes |
forceRefresh | true = live sync with the settlement network before responding (slower). Default false | Optional |
Authorization | Authorization token for API access (header) | Yes |
Content-Type | application/json (header) | Yes |
Sample Response
{
"result": {
"requestId": "8efee8d1-fac1-4906-aede-a3f090dbbcf8",
"status": "PAID",
"challanType": "ONLINE",
"vehicleNo": "UP16CP8145",
"challanNumber": "UP4190935251213064164",
"currency": "INR",
"challanAmount": "2000.00",
"convenienceFee": "300.00",
"totalCharged": "2300.00",
"refundAmount": "0.00",
"paymentReceipt": "https://<receipt-link>.pdf",
"failureReason": null,
"paidAt": "2026-08-02T14:03:11.000Z",
"lastUpdatedAt": "2026-08-02T14:03:11.000Z"
}
}Response Parameters
PARAMETER NAME | REQUIRED/OPTIONAL | DATA TYPE | DESCRIPTION |
|---|---|---|---|
requestId | Yes | string (uuid) | The payment reference that was queried |
status | Yes | string | Current lifecycle status — see the table in the Introduction |
challanType | Yes | string | ONLINE / OFFLINE |
vehicleNo | Yes | string | Vehicle the challan belongs to |
challanNumber | Yes | string | The challan being paid |
currency | Yes | string | Always INR |
challanAmount | Yes | string | Challan (fine) amount charged |
convenienceFee | Yes | string | Convenience fee charged |
totalCharged | Yes | string | challanAmount + convenienceFee — charged to your wallet |
refundAmount | Yes | string | Amount refunded back to your wallet (partial settlement or reversal) |
paymentReceipt | Optional | string | Receipt link, present once PAID. Links are time-limited — fetch a fresh one at download time rather than storing it |
failureReason | Optional | string | Populated when the payment ends FAILED |
paidAt | Optional | string | Settlement timestamp once PAID |
lastUpdatedAt | Yes | string | Last time this payment record changed |
Status Codes
CODE | REASON | MESSAGE |
|---|---|---|
400 | VALIDATION_ERROR | requestId is required / requestId is not valid |
401 | UNAUTHORIZED | Not Authorized to perform this action |
404 | NOT_FOUND | Payment request not found |
Getting help
Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better.
You can reach out to us at [email protected].