Skip to main content
The Phoenix Java middleware provides a comprehensive biller management system that allows you to retrieve biller categories, get billers by category, and fetch payment items for specific billers.

​
How biller management works

The biller management functionality is built around three main operations:
1

Get biller categories

Retrieve all available biller categories for your terminal. Categories group related billers together (e.g., utilities, telecommunications, government services).
2

Get billers by category

Once you have a category ID, fetch all billers within that category to present payment options to your users.
3

Get payment items

For a specific biller, retrieve all available payment items (products or services) that customers can pay for.

​
Controller implementation

All biller-related endpoints are exposed through the PaymentsController class:
PaymentsController.java:43-59
@GetMapping("/billerCategories")
public String getBillerCategories() throws Exception {

    return paymentsService.getCategories();
}

@GetMapping("/categoryBillers")
public String getBillersByCategory(@PathParam("categoryId") String categoryId) throws Exception {

    return paymentsService.getCategoryBillers(categoryId);
}

@GetMapping("/billerItems")
public String getPaymentItemsByBiller(@PathParam("billerId") String billerId) throws Exception {

    return paymentsService.getBillerItems(billerId);
}

​
Authentication requirements

All biller management endpoints require successful key exchange before making requests. The middleware automatically handles this through the KeyExchangeService.
Each biller query operation:
  1. Performs a key exchange to obtain an auth token and terminal key
  2. Generates Interswitch authentication headers
  3. Makes the HTTP GET request to the Phoenix API
  4. Returns the response data

​
API endpoints

EndpointMethodDescription
/isw/payments/billerCategoriesGETRetrieve all biller categories
/isw/payments/categoryBillersGETGet billers for a specific category
/isw/payments/billerItemsGETGet payment items for a biller
The base URL for the middleware is localhost:8081 by default. All endpoints are prefixed with /isw/payments.

​
Next steps

Get categories

Learn how to retrieve biller categories

Get billers

Fetch billers by category ID

Get payment items

Retrieve payment items for a biller

Build docs developers (and LLMs) love

Get started for freeTalk to us