#Webhooks
Here is the general structure of any webhook—
{"traceId" : "C3SFG0O6N88R6UI7EQ","timeStamp" : "2021-11-12T00:12:29+05:30","event" : "BILLER_UPDATES","data" : { /* Present on success */ },"error" : { /* Present on failure */ }}
traceIdis a unique ID assigned to the error and used by Setu to debugtimeStampdenotes the time when the webhook was triggeredeventis a pre-defined list of event types used to define what the webhook was triggered fordatacontains the webhook payload data on successful completion of the event.errorcontains details about the failure if the event could not be completed successfully. It typically includescodeandmessagefields. One ofdataorerrorwill be present.
#Bill fetch webhook
This webhook can be used to get details of outstanding bills on BBPS. It will only be triggered if the Fetch bill API is consumed. If the bill does not exist then suitable error message will be sent.
Method : POSTURL : To be provided by partner
Bill fetch sample request
{"event": "BILL_FETCH","timeStamp": "2023-08-27T17:09:24.566+05:30","data": {"bill": {"amount": 60500,"billDate": "2023-06-02","billNumber": "3749280326878517751","billPeriod": "Monthly","customerName": "Elijah White","dueDate": "2023-06-02"},"billerRefId": "9540207519","exactness": "Exact","refId": "CJLJBQK91PA0FD9MPMK0W75BD9M32391709","status": "Success","upmsRegistrationRefId": "CJLJBQK91PA0FD9MPMK0W75BD9M32391709"}}
Note: When a bill is presented automatically for a registered customer, this callback will include an additional field
upmsRegistrationRefIdwithin thedataobject, linking the bill to the specific registration. If this field is absent or null, the callback corresponds to a manual bill fetch request. See example below.
Bill presentment sample request
{"event": "BILL_FETCH","timeStamp": "2025-04-17T17:56:55.159+05:30","data": {"additionalInfo": [{"name": "Biller Unique Number","value": "Scaroasis"}],"billerResponseType": "SINGLE","billerSelectionType": null,"bills": [{"amount": 83400,"billDate": "2025-04-17","billNumber": "BILL-226131","billPeriod": "MONTHLY","customerName": "Nitin Gupta","dueDate": "2025-05-02","paymentOptions": [{"amount": 75060,"name": "Early Payment Amount"},{"amount": 91740,"name": "Late Payment Amount"}]}],"exactness": "RANGE","refId": "D00F73QLFUHJFPQC2800HVDeelt51071756", // Ref ID for this specific generated bill. Use this to initiate a payment."status": "Success","upmsRegistrationRefId": "D00EP9IJSBI05F06U9K0eBQWOq851071727" // Links to the UPMS registration}}
#Bill payment webhook
This informs you that NPCI has received the payment request for a particular bill. It will also pass on relevant errors and messages.
Method : POSTURL : To be provided by partner
Bill payment sample request
{"event": "BILL_PAY","data": {"refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202","status": "PROCESSING/SUCCESS/FAILURE","billerRefId": "ABC1235","transactionId": "AX01122999900001","failureReason": {"code": "BRR005","message": "Biller not accepting payments at the moment"},"paymentDetails": {"mode": "Internet Banking/Debit Card/Credit Card/IMPS/Cash/UPI/Wallet/NEFT/Prepaid Card/AEPS/Account Transfer/Bharat QR/USSD","paymentRefId": "N2001121212344","amount": 10000,"timestamp": "2020-12-12T13:12:00+05:30"},"billerId": "VODA00000MUM03"},"success": true,"traceId": "C3SFG0O6N88R6UI7EQ","error": null}
#Dispute webhook
This webhook can be used to view the status update for a dispute raised by a customer.
Method : POSTURL : To be provided by partner
Dispute sample request
{"event": "BILL_DISPUTE","data": {"refId": "JPMRPBOGGDTP1EFRZVXVESQVQIS10461642","disputeId": "OP0121046567755","status": "INITIALIZED/ASSIGNED/RE_ASSIGNED/ASSIGNED_TO_BOU/ASSIGNED_TO_COU/ASSIGNED_TO_OU/ESCALATED/RESOLVED/UNRESOLVED","assignedTo": "AX39","remarks": "Resolved in favour of customer"},"success": true,"error": null}
#Biller updates webhook
This is used to notify you about updates on any BBPS biller—including biller being added to or modified on the BBPS platform. In case of a biller gets modified, the request contains the biller with the new modification.
Method : POSTURL : To be provided by partner
Biller updates sample request
{"event": "BILLER_UPDATES","traceId": "C6I7O22PC5TNLVD7QSKG","timeStamp": "2021-11-29T12:36:48.910+05:30","data": [{"ID": 699158487875191900,"Status": "ACTIVE","BillerAcceptsAdhoc": "F","BillerAdditionalInfo": [{"DataType": "ALPHANUMERIC","Optional": true,"ParamName": "URL"},{"DataType": "ALPHANUMERIC","Optional": true,"ParamName": "Early Payment Date"}],"BillerAdditionalInfoPayment": null,"BillerAliasName": "TATA PWR - MUM","BillerCategoryName": "DTH","BillerCoverage": "IND","BillerCustomerParams": [{"dataType": "NUMERIC","maxLength": 12,"minLength": 12,"paramName": "Consumer Number"}],"BillerDescription": "","BillerEffctvFrom": "2017-10-31","BillerEffctvTo": "2025-12-31","BillerID": "ZEE500000NAT01","BillerMode": "ONLINE","BillerName": "ZEE TV","BillerOwnerShp": "Private","BillerPaymentChannels": [{"minLimit": 100,"maxLimit": 500000000,"paymentChannel": "INT"},{"minLimit": 100,"maxLimit": 500000000,"paymentChannel": "INTB"},{"minLimit": 100,"maxLimit": 500000000,"paymentChannel": "MOB"},{"minLimit": 100,"maxLimit": 500000000,"paymentChannel": "MOBB"},{"minLimit": 100,"maxLimit": 500000000,"paymentChannel": "POS"},{"minLimit": 100,"maxLimit": 500000000,"paymentChannel": "MPOS"},{"minLimit": 100,"maxLimit": 500000000,"paymentChannel": "ATM"},{"minLimit": 100,"maxLimit": 500000000,"paymentChannel": "BNKBRNCH"},{"minLimit": 100,"maxLimit": 500000000,"paymentChannel": "KIOSK"},{"minLimit": 100,"maxLimit": 500000000,"paymentChannel": "AGT"},{"minLimit": 100,"maxLimit": 500000000,"paymentChannel": "BSC"}],"BillerPaymentModes": [{"minLimit": 1,"paymentMode": "Internet Banking"},{"minLimit": 1,"paymentMode": "Debit Card"},{"minLimit": 1,"paymentMode": "Credit Card"},{"minLimit": 1,"paymentMode": "Prepaid Card"},{"minLimit": 1,"paymentMode": "IMPS"},{"minLimit": 1,"paymentMode": "Cash"},{"minLimit": 1,"paymentMode": "UPI"},{"minLimit": 1,"paymentMode": "Wallet"},{"minLimit": 1,"paymentMode": "NEFT"},{"minLimit": 1,"paymentMode": "AEPS"},{"minLimit": 1,"paymentMode": "Account Transfer"}],"BillerResponseParams": {"amountOptions": [{"amountBreakupSet": ["BASE_BILL_AMOUNT"]},{"amountBreakupSet": ["Early Payment Amount"]}]},"BillerTempDeactivationEnd": "","BillerTempDeactivationStart": "","BillerTimeOut": "","CustomerParamGroups": {"groups": null},"FetchRequirement": "MANDATORY","InterchangeFee": null,"ParentBiller": "","PaymentAmountExactness": "EXACT","PlanAdditionalInfo": null,"PlanMdmRequirement": "","SupportBillValidation": "","SupportDeemed": "","SupportPendingStatus": "","NameVector": "'mum':3 'pwr':2 'tata':1 'tv':5 'zee':4"}]}
#Biller Plan updates webhook
This is used to notify you about updates on any BBPS biller's plan — including additions and modification of plans. In case of a plan gets modified, the request contains the plan with the new modification.
Method : POSTURL : To be provided by partner
Biller plan updates sample request
{"event": "PLAN_UPDATES","timeStamp": "2025-04-08T12:34:29.603+05:30","data": {"billerId": "ZEE500000NAT01","Id": "3","amountInRupees": "599.0","categoryType": "Premium","categorySubType": {"subType": "6 Months"},"description": "All ZEE5 Originals and Exclusives, Blockbuster Movies, All ALT Balaji Shows, Zindagi TV Shows, Kids, Live TV, TV shows before telecast. Watch on 5 devices at a time","effectiveFrom": "2021-01-01","effectiveTo": "2021-12-31","status": "ACTIVE"}}
#Create UPMS Registration webhook
This webhook informs you about the final status (Success, Failed, or Duplicate) of a UPMS registration request initiated via the Fetch Bill and Create Registration API. The refId in the webhook payload matches the upmsRegistration.refId from the synchronous API response.
Method : POSTURL : To be provided by partner (Registration Callback URL)
Create UPMS Registration sample request (Success)
{"event": "CREATE_UPMS_REGISTRATION","traceId": "D07LJTJ71N0PUBJKS640","timeStamp": "2025-04-28T16:05:34.762+05:30","data": {"registration": {"refId": "D07LJTB71N0PGH5KG32G6dH2QjK51181605", // Unique reference ID for this registration"status": "SUCCESS", // Final status of the registration"biller": { // Same as the biller object in the request"id": "ABLP01000ANP03"},"customer": { // Same as the customer object in the request, except for the name field"customerParams": [{"name": "Roll No","value": "14989991"}],"mobile": "7378926241","name": "Anjali Desai" // NEW: Optional, only present if the biller shares the customer name},"mandate": { // Same as the mandate object in the request"billPeriod": "ASPRESENTED","billerParams": [{"name": "Low Balance Threshold","value": "500"}],"debitInfo": {"amount": 999999999,"currency": 356,"debitDate": "10-Feb","paymentMode": "Debit Card","type": "FIXED_AMOUNT"},"registrationType": "AUTO_PAY","toDate": "2025-12-22"},"createdAt": "2025-04-28T10:35:33Z", // Timestamp of the registration creation"updatedAt": "2025-04-28T10:35:34Z" // Timestamp of the last registration modification}},"refId": "D07LJTB71N0PGH5KG32G6dH2QjK51181605" // Matches registration.refId}
Create UPMS Registration sample request (Failed)
{"event": "CREATE_UPMS_REGISTRATION","timeStamp": "2025-03-11T10:20:00.000+05:30","refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102204", // Reference ID of the FAILED attempt from sync response"error": {"code": "biller-registration-failed","message": "Failed to register with Biller"},"traceId": "D07LJTJ71N0PUBJKS640" // Trace ID for this callback}
Create UPMS Registration sample request (Duplicate)
{"event": "CREATE_UPMS_REGISTRATION","traceId": "CVVQVLN5STDFRUU0LLFG","timeStamp": "2025-04-16T18:55:42.758+05:30","data": {"duplicate": {"code": "duplicate-upms-registration","message": "Successful UPMS registration already exists","refId": "CVVQFN8BT5ONNAN3JCO059wmPQX51061821" // Ref ID of the EXISTING registration}},"refId": "CVVQVLGBT5ONNAN3JD90qXrHAWg51061855" // Ref ID of the DUPLICATE attempt from sync response}
#Update UPMS Registration webhook
This webhook confirms the outcome (Success or Failed) of a request to update an existing customer registration using the Update Registration API. The refId in the webhook payload matches the upmsRegistrationRefID used in the API request path.
Method : POSTURL : To be provided by partner (Registration Callback URL)
Update UPMS Registration sample request (Success)
{"event": "UPDATE_UPMS_REGISTRATION","traceId": "D07MLCSRLASJ2P3SVAI0","timeStamp": "2025-04-28T17:16:59.941+05:30","data": {"registration": { // Contains the full, updated registration details"refId": "D07ML76AIQNN6974G200emsL9K451181716","status": "SUCCESS","biller": {"id": "ABLP01000ANP03"},"customer": {"customerParams": [{"name": "Roll No","value": "67d88976"}],"mobile": "9039403265","name": "Gautam Rajput"},"mandate": {"billerParams": [{"name": "Low Balance Threshold","value": "500"}],"debitInfo": {"amount": 999999999,"currency": 356,"debitDate": "10-Feb","paymentMode": "Internet Banking","type": "FIXED_AMOUNT"},"registrationType": "AUTO_PAY","toDate": "2025-12-22"},"createdAt": "2025-04-28T11:46:36Z","updatedAt": "2025-04-28T11:46:59Z" // Reflects the update time}},"refId": "D07ML76AIQNN6974G200emsL9K451181716" // Matches the updated registration's refId}
Update UPMS Registration sample request (Failed)
{"event": "UPDATE_UPMS_REGISTRATION","traceId": "D07N6PSRLASJ2P3SVAMG","timeStamp": "2025-04-28T17:54:07.062+05:30","refId": "D07N6M6AIQNN6974G9EGH18p7p051181753", // The refId of the attempted update"error": {"code": "biller-update-registration-failed","message": "Failed to update registration with Biller"}}
#Cancel UPMS Registration webhook
This webhook confirms the outcome (Success or Failed) of a request to cancel an existing UPMS registration using the Cancel Registration API. The refId in the webhook payload matches the upmsRegistrationRefID used in the API request path.
Method : POSTURL : To be provided by partner (Registration Callback URL)
Cancel UPMS Registration sample request (Success)
{"event": "CANCEL_UPMS_REGISTRATION","traceId": "D07MLCSRLASJ2P3SVAI0", // Example Trace ID"timeStamp": "2025-04-28T17:16:59.941+05:30", // Example Timestamp"data": {"registration": { // Contains details of the cancelled registration"refId": "D07ML76AIQNN6974G200emsL9K451181716","status": "CANCELLED","biller": { /* ... biller details ... */ },"customer": { /* ... customer details ... */ },"mandate": { /* ... mandate details ... */ },"createdAt": "2025-04-28T11:46:36Z","updatedAt": "2025-04-28T11:46:59Z" // Time of cancellation}},"refId": "D07ML76AIQNN6974G200emsL9K451181716" // Matches the cancelled registration's refId}
Cancel UPMS Registration sample request (Failed)
{"event": "CANCEL_UPMS_REGISTRATION","traceId": "D07N6PSRLASJ2P3SVAMG", // Example Trace ID"timeStamp": "2025-04-28T17:54:07.062+05:30", // Example Timestamp"refId": "D07N6M6AIQNN6974G9EGH18p7p051181753", // The refId of the attempted cancellation"error": {"code": "registration-cancellation-failed","message": "Failed to cancel registration with Biller"}}
#Skip Payment webhook
This webhook notifies you when a bill, previously presented via UPMS, has been paid through an external channel (e.g., directly on the biller's site, another app). Use this to update the bill's status in your system.
Method : POSTURL : To be provided by partner (Skip Payment Callback URL)
Skip Payment sample request
{"event": "SKIP_PAYMENT","traceId": "D0508DIBJFBLCSGI36RG","timeStamp": "2025-04-25T18:16:46.716+05:30","data": {"billRefId": "D050862BJFBLCSGI36N0e3qv9Zu51151816", // The refId of the bill that was paid externally"dateOfPayment": "2025-04-25T18:16:44+05:30" // Timestamp of the external payment}}
Was this page helpful?