Skip to main content

​
Quickstart

This guide will help you get the Phoenix Java Middleware running quickly using the pre-built JAR file or by building from source.

​
Prerequisites

Before you begin, ensure you have:
  • Java 17 or higher (OpenJDK recommended)
  • Phoenix API credentials from Interswitch Uganda
  • A text editor for configuration
The middleware runs on port 8081 by default. Make sure this port is available.

​
Option 1: Run the pre-built JAR

The fastest way to get started is using the pre-built JAR from the /dist folder.
1

Download or clone the repository

Clone the repository from GitHub:
git clone https://github.com/jonahokot/phoenix-java-middleware.git
cd phoenix-java-middleware
2

Configure your credentials

Update the dist/application.properties file with your Phoenix API credentials:
app.client_id=YOUR_CLIENT_ID
app.client_secret=YOUR_CLIENT_SECRET
app.terminal_id=YOUR_TERMINAL_ID
See the Configuration guide for all available settings.
3

Run the JAR

Execute the JAR file using Java:
java -jar dist/phoenix-api-middleware-1.0.0.jar
The application will start on http://localhost:8081.

​
Option 2: Build from source

If you want to build the middleware yourself or make custom modifications:
1

Clone the repository

git clone https://github.com/jonahokot/phoenix-java-middleware.git
cd phoenix-java-middleware
2

Configure credentials

Edit src/main/resources/application.properties with your credentials:
app.client_id=YOUR_CLIENT_ID
app.client_secret=YOUR_CLIENT_SECRET
app.terminal_id=YOUR_TERMINAL_ID
3

Build with Maven

Use the Maven wrapper to build the project:
./mvnw clean package
The JAR will be created in the target/ directory.
4

Run the application

java -jar target/phoenix-api-middleware-1.0.0.jar

​
Verify the installation

Once the application is running, verify it’s working correctly:
1

Check the application status

The console should display:
Started PhoenixSimulatorApplication in X.XXX seconds
2

Test the key generation endpoint

Generate RSA keys for client registration:
curl http://localhost:8081/isw/auth/generateKeys
You should receive a response with public and private keys:
{
  "publicKey": "MIIBIjANBgkqhki...",
  "privateKey": "MIIEvgIBADANBgk..."
}
3

Test key exchange

Perform a key exchange to establish a session:
curl http://localhost:8081/isw/auth/keyExchange
The middleware automatically handles key exchange before payment operations, so you don’t need to call it manually for each transaction.

​
Available endpoints

The middleware exposes the following REST endpoints:

​
Authentication

  • GET /isw/auth/generateKeys - Generate RSA key pairs
  • POST /isw/auth/registerClient - Register a new client
  • GET /isw/auth/keyExchange - Perform key exchange

​
Payments

  • POST /isw/payments/validation - Validate customer account
  • POST /isw/payments/pay - Process payment
  • GET /isw/payments/checkStatus - Check transaction status
  • GET /isw/payments/balance - Get wallet balance

​
Billers

  • GET /isw/payments/billerCategories - Get biller categories
  • GET /isw/payments/categoryBillers - Get billers by category
  • GET /isw/payments/billerItems - Get payment items
Import the included Postman collection (Phoenix API Sample.postman_collection.json) for easy testing of all endpoints.

​
Next steps

Configuration

Configure all application settings

Authentication

Learn about the authentication flow

Process payments

Start processing payments

API reference

Explore the complete API
Remember to update your client secret after completing the registration process, as a new secret is issued upon successful registration.

Build docs developers (and LLMs) love

Get started for freeTalk to us