Skip to main content
Once you have a category ID, you can fetch all billers that belong to that category. This allows you to present users with a filtered list of payment providers based on their selected category.

​
Endpoint details

GET /isw/payments/categoryBillers?categoryId={categoryId}

​
Query parameters

​
categoryId
string
required
The unique identifier of the biller category

​
Controller implementation

The endpoint is defined in PaymentsController:
PaymentsController.java:49-53
@GetMapping("/categoryBillers")
public String getBillersByCategory(@PathParam("categoryId") String categoryId) throws Exception {

    return paymentsService.getCategoryBillers(categoryId);
}

​
Service implementation

The getCategoryBillers() method in PaymentsService handles the biller retrieval:
PaymentsService.java:121-134
public String getCategoryBillers(String categoryId) throws Exception {

	String endpointUrl =  Constants.BILLERS_ROOT +  "biller-by-category/"+categoryId;

	SystemResponse<KeyExchangeResponse> exchangeKeys = keyExchangeService.doKeyExchange();

	if(exchangeKeys.getResponseCode().equals(PhoenixResponseCodes.APPROVED.CODE)) {
		Map<String,String> headers = AuthUtils.generateInterswitchAuth(Constants.GET_REQUEST, endpointUrl, "",exchangeKeys.getResponse().getAuthToken(),exchangeKeys.getResponse().getTerminalKey());
		return HttpUtil.getHTTPRequest(endpointUrl, headers);
	}
	else {
		return "Cannot Fetch Billers,Key Exchange failed";
	}
}

​
How it works

1

Receive category ID

The endpoint accepts a category ID as a query parameter.
2

Perform key exchange

Obtains fresh authentication credentials from the key exchange service.
3

Build endpoint URL

Constructs the Phoenix API endpoint: {BILLERS_ROOT}/biller-by-category/{categoryId}
4

Generate authentication

Creates Interswitch auth headers using the obtained auth token and terminal key.
5

Execute request

Sends the GET request and returns all billers in the specified category.

​
Making a request

Example request using the Postman collection: 
curl "http://localhost:8081/isw/payments/categoryBillers?categoryId=10"
The example uses category ID 10. Replace this with an actual category ID obtained from the /billerCategories endpoint.

​
Error handling

If key exchange fails, the service returns: “Cannot Fetch Billers,Key Exchange failed”
Common issues:
  • Invalid category ID: Verify the category exists using the /billerCategories endpoint
  • Authentication failure: Check your client credentials in application.properties
  • Network issues: Ensure connectivity to the Phoenix API

​
Response format

The endpoint returns a JSON response containing all billers in the category. Each biller includes:
  • Biller ID (needed to fetch payment items)
  • Biller name
  • Description
  • Available payment methods
  • Other biller-specific metadata

​
Typical workflow

​
Next steps

Get biller categories

Learn how to retrieve category IDs

Get payment items

Fetch payment items for a selected biller

Build docs developers (and LLMs) love

Get started for freeTalk to us