Skip to main content
Biller categories group related billers together, making it easier for users to navigate and find the services they want to pay for. This endpoint returns all categories available to your terminal.

​
Endpoint details

GET /isw/payments/billerCategories This endpoint does not require any parameters and returns all biller categories configured for your terminal ID.

​
Service implementation

The getCategories() method in PaymentsService handles the category retrieval:
PaymentsService.java:106-119
public String getCategories() throws Exception {

	String endpointUrl =  Constants.BILLERS_ROOT +  "categories-by-client/"+Constants.TERMINAL_ID+"/"+ Constants.TERMINAL_ID;

	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 Categories,Key Exchange failed";
	}
}

​
How it works

1

Key exchange

The service performs a key exchange operation to obtain authentication credentials.
2

Build endpoint URL

Constructs the full endpoint URL using the billers root and terminal ID: {BILLERS_ROOT}/categories-by-client/{TERMINAL_ID}/{TERMINAL_ID}
3

Generate auth headers

Creates Interswitch authentication headers using the auth token and terminal key from the key exchange.
4

Make HTTP request

Sends a GET request to the Phoenix API and returns the response containing all available categories.

​
Making a request

Use the Postman collection or make a direct HTTP request: 
curl http://localhost:8081/isw/payments/billerCategories
The middleware automatically handles authentication, so you don’t need to manually include auth headers when calling the middleware endpoints.

​
Error handling

If the key exchange fails, the service returns the error message: “Cannot Fetch Categories,Key Exchange failed”
Ensure that:
  • Your client credentials are properly configured in application.properties
  • The terminal ID is valid and active
  • Network connectivity to the Phoenix API is available

​
Response format

The endpoint returns a JSON response containing all available biller categories. Each category includes:
  • Category ID (used to fetch billers in that category)
  • Category name
  • Category description
  • Other metadata

​
Next steps

Once you have the category IDs, you can:

Get billers by category

Use the category ID to retrieve all billers within that category

Build docs developers (and LLMs) love

Get started for freeTalk to us