Handling Bill Payment API Responses & Errors
API Respons
Response CodesThese codes are returned in the
response_code
field of the API response.Code | Description |
---|---|
0 | API call was successful. Check payload for details. |
1 | API call failed. Check response_code and payload for the reason. |
36 | Velocity limit breached. |
37 | Velocity limit breached. |
38 | Duplicate referenceId provided. |
HTTP Status CodesThe API also uses standard HTTP status codes to indicate the result of the HTTP request.
HTTP Code | Meaning |
---|---|
400 | Bad request. This could be a field validation error or invalid biller ID. |
412 | Missing or invalid input parameters, type mismatch, invalid checksum, or invalid nodal bank/company ID. Also triggered if both bank account and VPA are provided together. |
422 | The specified biller is not active. |
500 | Internal server error. Could include bill fetch failures. |
502 | Server down. |
503 | Service unavailable. |
504 | Gateway timeout. Suggests trying again after a delay. |
HTTP Status CodesThe request was successfully processed. Check the Indicates a problem with your request (like invalid data or failed validation). Treat this as a hard failure. Review and correct your request data before retrying. Check The server encountered an issue or timed out. Wait 2–3 minutes, then use the Get Utility Bill Status API to run an enquiry: If the enquiry returns transaction details, your original request likely completed. If it returns a
✅ 2XX (Success)
billPayStatus
and paymentStatus
fields in the response payload to determine the actual transaction outcome.❌ 4XX (Client Errors)
response_code
and payload
in the response for details.⚠️ 5XX (Server Errors)
400
with payload: "No utility payment found"
, the transaction did not go through—so it’s safe to retry.Checking the Payload for 2XX Responses 🧾
2XX
HTTP response, inspect these fields in the JSON payload to determine the final payment outcome:billPayStatus
Indicates the bill payment status:
SUCCESS
: 🎉 Bill payment completed successfully.FAILED
: 😞 Payment failed. Check paymentStatus
and failureReason
.IN_PROGRESS
: ⏳ Waiting for confirmation from the biller.PENDING
: ➡️ Payment request has been initiated but is not yet complete.paymentStatus
(used when billPayStatus
is FAILED
or IN_PROGRESS
)FAILED
: Wallet debit failed (for example, due to insufficient funds).REFUNDED
: Payment failed, and the amount was refunded to your wallet.IN_PROGRESS
or PENDING
: Still processing.failureReason
billPayStatus
is FAILED
, this provides the detailed reason for the failure.Modified at 2025-07-06 07:02:46