Skip to main content

​
Configuration

The Phoenix Java Middleware is configured through the application.properties file. This guide covers all available configuration options.

​
Configuration file location

Depending on how you run the middleware, the configuration file is located at:
  • Pre-built JAR: dist/application.properties
  • Source build: src/main/resources/application.properties

​
Required configuration

You must update these settings with your actual Phoenix API credentials before running the middleware. The default values are for demonstration only.

​
Server configuration

​
server.port
integer
default:"8081"
The port on which the middleware will run. Default is 8081.
server.port = 8081

​
Phoenix API credentials

These credentials are provided by Interswitch Uganda when you register for the Phoenix API.
​
app.client_id
string
required
Your Phoenix API client ID.
app.client_id=IKIAB5D9BB39928575119F0F680926FABB0C00B93197
​
app.client_secret
string
required
Your Phoenix API client secret. This value is updated after successful client registration.
app.client_secret=b/Pv7X7SH2Asu5NJ8AITyiBMiBx9Y4fuyrXRWmm1i5Y=
After completing client registration, a new client secret is issued. You must update this value in the configuration file.
​
app.terminal_id
string
required
Your terminal identifier.
app.terminal_id=3ISO7027

​
Cryptographic keys

​
app.public_key
string
required
Your RSA public key in Base64 format. Generate this using the /isw/auth/generateKeys endpoint or use existing keys.
app.public_key=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp8J3DnDB...
​
app.private_key
string
required
Your RSA private key in Base64 format. Keep this secure and never share it.
app.private_key=MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCnw...
Use the /isw/auth/generateKeys endpoint to generate a new RSA key pair if you don’t have one.

​
Application metadata

​
app.serial_id
string
required
Serial ID for your application instance.
app.serial_id=12345
​
app.version
string
default:"v1"
API version to use.
app.version=v1
​
app.password
string
required
Application password for authentication.
app.password=12345

​
Phoenix API endpoints

​
app.base_url
string
required
The base URL for Phoenix API operations.
app.base_url=https://dev.interswitch.io/api/v1/phoenix/
​
app.billers_base_url
string
required
The base URL for biller-related operations.
app.billers_base_url=https://dev.interswitch.io/api/v1/phoenix/gateway/qt-api/Biller/
The URLs shown above are for the development/sandbox environment. Use production URLs when deploying to production.

​
Complete configuration example

Here’s a complete example of the application.properties file: 
server.port = 8081

# Phoenix API Credentials
app.client_id=IKIAB5D9BB39928575119F0F680926FABB0C00B93197
app.client_secret=b/Pv7X7SH2Asu5NJ8AITyiBMiBx9Y4fuyrXRWmm1i5Y=
app.terminal_id=3ISO7027

# RSA Keys
app.public_key=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp8J3DnDB...
app.private_key=MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCnw...

# Application Metadata
app.serial_id=12345
app.version=v1
app.password=12345

# Phoenix API Endpoints
app.base_url=https://dev.interswitch.io/api/v1/phoenix/
app.billers_base_url=https://dev.interswitch.io/api/v1/phoenix/gateway/qt-api/Biller/

​
Configuration steps

1

Obtain credentials

Register with Interswitch Uganda to receive your Phoenix API credentials including client ID, terminal ID, and access to the API environments.
2

Generate keys

Use the middleware’s key generation endpoint or generate RSA keys externally:
curl http://localhost:8081/isw/auth/generateKeys
3

Update configuration

Edit the application.properties file with your credentials and generated keys.
4

Register client

After starting the middleware, register your client using the /isw/auth/registerClient endpoint. This will issue a new client secret.
5

Update client secret

Update the app.client_secret value in application.properties with the new secret from the registration response.
6

Restart the application

Restart the middleware for the new client secret to take effect.

​
Environment-specific configuration

For different environments (development, staging, production), maintain separate configuration files: 
application.properties              # Default
application-dev.properties         # Development
application-staging.properties     # Staging
application-prod.properties        # Production
Run with a specific profile: 
java -jar phoenix-api-middleware-1.0.0.jar --spring.profiles.active=prod

​
Security best practices

Follow these security practices to protect your credentials:
  • Never commit application.properties with real credentials to version control
  • Use environment variables or secret management tools for production deployments
  • Rotate keys regularly and update the client secret after registration
  • Restrict access to the configuration file using file system permissions
  • Use HTTPS when deploying the middleware to production

​
Next steps

Authentication

Learn about the authentication flow

Client registration

Register your client with Phoenix API

Build docs developers (and LLMs) love

Get started for freeTalk to us