—
–
/

to search

Introducing Setu Changelog Check it out ↗

Reading time — 4 minutes

Edit this page ↗

#API Polling

This set of APIs has been deprecated. It is recommended to use these APIs instead.


BillPay COU APIs are asynchronous and require a polling mechanism to retrieve results. The duration for the intervals between polling and end states are documented below.

We strongly recommend using a persistent queue like RabbitMQ to process these APIs.

#Flowchart for polling logic

These APIs are mandatory to consume, and asynchronous and dependent on each other. The APIs that require polling logic—

Bill fetch APIs
bill-fetch-request and get-fetched-bill

Bill payment APIs
make-payment and get-payment-status

#Bill fetch APIs

The Bill Fetch APIs are used to retrieve outstanding bills from a biller. These are the bill-fetch-request and get-fetched-bill APIs.

The context from the response for bill-fetch-request has to be passed as the request for get-fetched-bill.

The get-fetched-bill API must be called 5 secs after a successful bill-fetch-request—

  • If the fetchAPIStatus, from response of get-fetched-bill, is Acknowledged it means that the request is still processing. You'll need to re-hit the get-fetched-bill with the same context again after 5 secs and wait for fetchAPIStatus to become Active.
  • If the fetchAPIStatus does not become Active after retrying the same for 1 minute you can terminate the bill fetch and display an error.

If either bill-fetch-request or get-fetched-bill has an error/timeout and does NOT give a response, you can retry the APIs with the same request body.


If fetchAPIStatus, from get-fetched-bill response is—

  • Acknowledged—The request is still processing. Retry after 5 secs.
  • Cancelled—The request has finished processing but there was an error. You can display the provided error message.
  • Rejected—The request finished processing but there was an error. You can display the provided error message.
  • Active—The request has finished processing successfully. You can display the bill and redirect the user to payment screens.

#Make payment APIs

The make-payment and get-payment-status APIs are used to complete payment for outstanding bills of a biller.

The context from the response of get-fetched-bill has to be passed as the request for make-payment. Similarly, context from the response of make-payment has to be passed as the request for get-payment-status.

The get-payment-status API must be called 5 secs after a successful make-payment call—

  • If the status from the response of get-payment-status is Execution Awaited it means the request is still processing. You'll need to re-hit get-payment-status with the same context again after 5 secs and wait for status to become Settled or Cancelled or Rejected.
  • If the status does not go into an end state after retrying the same for 5 minutes, you can retry the get-payment-status with the same context again once every 5 minutes till it goes to an end state. If the end state is not Settled or Cancelled or Rejected even after 1 day, please contact us at Setu Support.

If the make-payment API errors/timeouts and does NOT give a response you can pass the context used in the make-payment request body as the context for get-payment-status request.

This will help you identify if the payment in question has been registered with the BBPS system.


Never call the make-payment API multiple times for the same context as it may result in your account getting debitted multiple times.


If the get-payment-status API errors/times out and does not give a response you can retry with the same request body.

If status, obtained in the response of get-payment-status is—

  • Execution Awaited—The request is still processing. Please retry after 5 secs.
  • Cancelled—The request has finished processing but there was an error. You can display the provided error message.
  • Rejected—The request has finished processing but there was an error. You can display the provided error message.
  • Settled—The request has finished processing successfully. You can display the receipt for your user.