Enkash Developer Portal
HomePayment GatewayPayoutsCreate Account
HomePayment GatewayPayoutsCreate Account
Login
  1. Home
  • Back to home
  • Bill Payment
  • Utility API Response Handling
  • Get Authentication Token
    POST
  • Get BillerTypes
    GET
  • Get Billers
    GET
  • Fetch Bill
    POST
  • Create Bill API
    POST
  • Create Bill Without Bill Fetch
    POST
  • Bill Payment
    POST
  • Utility Bill Approval API
    PUT
  • Get Utility Bill Status
    GET
  • Get Utility Bill by Reference Id
    GET
  • Get Utility Bills Detail
    POST
  • Bill Payment Webhook
    POST
  1. Home

Handling Bill Payment API Responses & Errors

EnKash’s Bill Payment API uses specific response codes and HTTP status codes to indicate the outcome of API requests. Properly handling these codes ensures clear communication, robust error handling, and seamless integration for your applications.
The guidance below applies to these APIs:
Create Bill Without Bill Fetch
Create Bill API
Get Utility Bill by Reference ID
Get Utility Bill Status
Bill Payment Webhook

API Respons#

Response Codes
These codes are returned in the response_code field of the API response.
CodeDescription
0API call was successful. Check payload for details.
1API call failed. Check response_code and payload for the reason.
36Velocity limit breached.
37Velocity limit breached.
38Duplicate referenceId provided.
HTTP Status Codes
The API also uses standard HTTP status codes to indicate the result of the HTTP request.
HTTP CodeMeaning
400Bad request. This could be a field validation error or invalid biller ID.
412Missing 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.
422The specified biller is not active.
500Internal server error. Could include bill fetch failures.
502Server down.
503Service unavailable.
504Gateway timeout. Suggests trying again after a delay.
HTTP Status Codes

✅ 2XX (Success)#

The request was successfully processed.
Check the billPayStatus and paymentStatus fields in the response payload to determine the actual transaction outcome.

❌ 4XX (Client Errors)#

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 response_code and payload in the response for details.

⚠️ 5XX (Server Errors)#

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 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 🧾#

If you receive a 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
If billPayStatus is FAILED, this provides the detailed reason for the failure.
Modified at 2025-07-06 07:02:46
Built with