Submit payment
Routes the payment to the biller and returns the reference that identifies this transaction everywhere afterwards.
Sample reference
This shows the shape of the call — the operation, its fields and what comes back. The exact paths, base URL and any extra fields are confirmed with your sandbox credentials.
{BASE_URL}/v1/bbps/payments🚧 A timeout is not a failure
Headers
AuthorizationstringrequiredBearer <your API key>. Sandbox and production keys are separate.
Content-Typestringrequiredapplication/json on every request that has a body.
Request body
billerIdstringrequiredFrom the biller catalogue.
billIdstringoptionalFrom fetch bill. Omit for billers without fetch.
amountnumberrequiredIn rupees.
customerParamsobjectrequiredThe same fields you validated.
clientReferencestringrequiredYour own unique ID. Sending it twice returns the first result instead of charging twice.
Response fields
referenceIdstringrequiredStore this. Use it for status checks, receipts and reconciliation.
statusstringrequiredPENDING, SUCCESS or FAILED. PENDING settles via webhook or the status call.
Values of status
| Value | Meaning |
|---|---|
| PENDING | Accepted and in progress. The final result arrives by webhook or the status call. |
| SUCCESS | Completed. Safe to show the customer a receipt. |
| FAILED | Did not go through. Show the reason; the customer can try again. |
Errors
Every API returns the same envelope on failure, so one handler covers the whole catalogue.
VALIDATION_ERRORA field is missing or malformed. The message names the field.
UNAUTHORIZEDThe API key is missing, wrong, or for the other environment.
NOT_FOUNDNo resource with that ID or reference exists.
DUPLICATE_REFERENCEThis clientReference was already used. Safe to treat as a repeat of the first call.
RATE_LIMITEDToo many requests. Back off and retry after the Retry-After header.
UPSTREAM_UNAVAILABLEThe biller, bank or network is down. Retry later; nothing was charged.