Skip to main content

​
Client registration

Client registration is a one-time process that registers your application with the Phoenix API and issues a new client secret that you’ll use for all subsequent API calls.

​
Registration process

The registration involves two API calls to Phoenix:
  1. Initial registration - Send client details and public key
  2. Complete registration - Confirm registration and receive new client secret
1

Generate keys

First, generate an RSA key pair if you haven’t already:
curl http://localhost:8081/isw/auth/generateKeys
Update application.properties with the keys.
2

Prepare registration data

Collect the required client information:
{
  "name": "Your Company Name",
  "phoneNumber": "256-XXX-XXXX",
  "nin": "National ID Number",
  "gender": "Male",
  "emailAddress": "[email protected]",
  "ownerPhoneNumber": "256-XXX-XXXX"
}
3

Call the registration endpoint

Submit your registration:
curl -X POST http://localhost:8081/isw/auth/registerClient \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Company Name",
    "phoneNumber": "256-XXX-XXXX",
    "nin": "123456789",
    "gender": "Male",
    "emailAddress": "[email protected]",
    "ownerPhoneNumber": "256-XXX-XXXX"
  }'
4

Save the new client secret

If successful, you’ll receive:
Successful, New Client Secret: YOUR_NEW_CLIENT_SECRET
Update application.properties:
app.client_secret=YOUR_NEW_CLIENT_SECRET
5

Restart the middleware

Restart to use the new client secret:
# Stop the current process, then:
java -jar phoenix-api-middleware-1.0.0.jar
You must update the client secret in application.properties and restart the application after successful registration.

​
Implementation details

The registration process uses both RSA and elliptic curve cryptography:

​
Initial registration

private String clientRegistrationRequest(String publicKey, String clientSessionPublicKey, 
                                         String privateKey, ClientRegistrationDetail setup) {
    
    String registrationEndpointUrl = Constants.ROOT_LINK + "client/clientRegistration";
    
    // Set required fields
    setup.setSerialId(Constants.MY_SERIAL_ID);
    setup.setTerminalId(Constants.TERMINAL_ID);
    setup.setPublicKey(publicKey);
    setup.setClientSessionPublicKey(clientSessionPublicKey);
    
    // Generate authentication headers
    Map<String,String> headers = AuthUtils.generateInterswitchAuth(
        Constants.POST_REQUEST, registrationEndpointUrl, "", "", "", privateKey
    );
    
    String json = JSONDataTransform.marshall(setup);
    return HttpUtil.postHTTPRequest(registrationEndpointUrl, headers, json);
}
Source: RegistrationService.java:113-129

​
Elliptic curve key exchange

During registration, an ECDH key pair is generated for secure session establishment: 
EllipticCurveUtils curveUtils = new EllipticCurveUtils("ECDH");
KeyPair keyPair = curveUtils.generateKeypair();
String curvePrivateKey = curveUtils.getPrivateKey(keyPair);
String curvePublicKey = curveUtils.getPublicKey(keyPair);
Source: RegistrationService.java:60-63

​
Complete registration

After Phoenix approves the initial registration: 
private String completeRegistration(String terminalKey, String authToken, 
                                   String transactionReference, String otp, 
                                   String privateKey) throws Exception {
    
    CompleteClientRegistration completeReg = new CompleteClientRegistration();
    
    String passwordHash = UtilMethods.hash512(Constants.ACCOUNT_PWD);
    completeReg.setTerminalId(Constants.TERMINAL_ID);
    completeReg.setSerialId(Constants.MY_SERIAL_ID);
    completeReg.setOtp(CryptoUtils.encrypt(otp, terminalKey));
    completeReg.setPassword(CryptoUtils.encrypt(passwordHash, terminalKey));
    completeReg.setTransactionReference(transactionReference);
    
    Map<String,String> headers = AuthUtils.generateInterswitchAuth(
        Constants.POST_REQUEST, registrationCompletionEndpointUrl,
        "", authToken, terminalKey, privateKey
    );
    
    String json = JSONDataTransform.marshall(completeReg);
    return HttpUtil.postHTTPRequest(registrationCompletionEndpointUrl, headers, json);
}
Source: RegistrationService.java:131-151

​
Extracting the client secret

The new client secret is encrypted with your public key: 
if(response.getResponse().getClientSecret() != null && 
   response.getResponse().getClientSecret().length() > 5) {
    
    String clientSecret = CryptoUtils.decryptWithPrivate(
        response.getResponse().getClientSecret(), privateKey
    );
    
    return "Successful, New Client Secret: " + clientSecret;
}
Source: RegistrationService.java:94-99

​
Registration fields

Required fields for client registration:
​
name
string
required
Your company or application name
​
phoneNumber
string
required
Contact phone number (Uganda format)
​
nin
string
required
National identification number
​
gender
string
required
Gender (Male/Female)
​
emailAddress
string
required
Contact email address
​
ownerPhoneNumber
string
required
Owner’s phone number

​
Troubleshooting

​
Registration failed

If registration fails, check:
  • Public and private keys are correctly set in application.properties
  • Client ID and terminal ID are valid
  • All required fields are provided
  • Network connectivity to Phoenix API

​
Invalid credentials error

Ensure:
  • Using the correct base URL for your environment (dev/prod)
  • Client ID matches the one provided by Interswitch
  • Keys were generated correctly
You can re-register at any time if you need to rotate credentials or if registration fails. Each successful registration issues a new client secret.

​
Next steps

Key exchange

Establish secure sessions

Process payments

Start making payments

Build docs developers (and LLMs) love

Get started for freeTalk to us