Webhooks

Here is the general structure of any webhook—

{
    "traceId"   : "C3SFG0O6N88R6UI7EQ",
    "timeStamp" : "2021-11-12T00:12:29+05:30",
    "event"     : "BILL_FETCH / BILL_PAY / BILL_DISPUTE / BILLER_UPDATES / PLAN_UPDATES / CREATE_UPMS_REGISTRATION / UPDATE_UPMS_REGISTRATION / CANCEL_UPMS_REGISTRATION / SKIP_PAYMENT",
    "data"      : { /* Present on success */ },
    "error"     : { /* Present on failure */ }
}

1. traceId is a unique ID assigned to the error and used by Setu to debug
2. timeStamp denotes the time when the webhook was triggered
3. event is a pre-defined list of event types used to define what the webhook was triggered for
4. data contains the webhook payload data on successful completion of the event.
5. error contains details about the failure if the event could not be completed successfully. It typically includes code and message fields. One of data or error will 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 : POST
URL    : To be provided by partner

Note: When a bill is presented automatically for a registered customer, this callback will include an additional field upmsRegistrationRefId within the data object, 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.

Val Add webhooks

Val Add APIs (Value Added Services) are asynchronous. After you initiate a Val Add request using /bbps/valadd/{requestType}/request, COU will send you a webhook with the final outcome for that operation.

Common event values include:

• VAL_ADD_GET_CUSTOMER_ID
• VAL_ADD_GENERATE_OTP
• VAL_ADD_VALIDATE_OTP
• VAL_ADD_GET_BANK_MARKUP
• VAL_ADD_FETCH_BEST_PRICE

Fallback: If you don't receive a webhook, you can poll the result using /bbps/valadd/{requestType}/response with the refId.

FX Mandate result webhook

After you initiate FX mandate booking using /bbps/bills/mandate/request, COU sends the final result using a dedicated webhook.

Fallback: If you don't receive a webhook, you can poll the booking status using /bbps/bills/mandate/response with the refId.

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 : POST
URL    : To be provided by partner

Dispute webhook

This webhook can be used to view the status update for a dispute raised by a customer.

Method : POST
URL    : To be provided by partner

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 : POST
URL    : To be provided by partner

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 : POST
URL    : To be provided by partner

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 : POST
URL    : To be provided by partner (Registration Callback URL)

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 : POST
URL    : To be provided by partner (Registration Callback URL)

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 : POST
URL    : To be provided by partner (Registration Callback URL)

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 : POST
URL    : To be provided by partner (Skip Payment Callback URL)