Skip to main content

​
Authentication overview

The Phoenix Java Middleware implements a secure multi-step authentication process using RSA and elliptic curve cryptography to establish secure sessions with the Interswitch Phoenix API.

​
Authentication flow

The complete authentication process consists of three main steps:
1

Generate RSA keys

Create an RSA public-private key pair that will be used for encrypting sensitive data during communication.
2

Register client

Register your application with the Phoenix API using your credentials and public key. This process issues a new client secret.
3

Perform key exchange

Execute a daily key exchange to establish a secure session key for encrypting transaction data.
Key exchange must be performed daily or before each transaction session to maintain secure communication.

​
Security architecture

The middleware uses a multi-layered security approach:

​
RSA encryption (2048-bit)

Used for:
  • Client registration
  • Encrypting session keys
  • Protecting sensitive credentials
Implementation: CryptoUtils.java using Java’s standard crypto libraries

​
Elliptic Curve Diffie-Hellman (ECDH)

Used for:
  • Session key exchange
  • Deriving shared secrets
  • Securing transaction-level encryption
Implementation: EllipticCurveUtils.java with Bouncy Castle provider

​
Signature-based authentication

Every API request includes:
  • Client ID signature
  • Request timestamp
  • Request hash
  • Authorization headers
Implementation: AuthUtils.java (AuthController.java:20-24)

​
Authentication components

​
AuthController

Exposes three REST endpoints: 
@RestController
@RequestMapping("isw/auth")
public class AuthController {
    
    @GetMapping("/generateKeys")
    public Map<String, String> clientRegistration() throws Exception {
        return registrationService.generateKeys();
    }
    
    @PostMapping("/registerClient")
    public String clientRegistration(@RequestBody ClientRegistrationDetail detail) {
        return registrationService.doRegistration(detail);
    }
    
    @GetMapping("/keyExchange")
    public SystemResponse<KeyExchangeResponse> keyExchange() throws Exception {
        return keyExchangeService.doKeyExchange();
    }
}
Source: AuthController.java:13-41

​
RegistrationService

Handles key generation and client registration: 
public Map<String,String> generateKeys() throws SystemApiException {
    KeyPair pair = CryptoUtils.generateKeyPair();
    String privateKey = Base64.encodeBase64String(pair.getPrivate().getEncoded());
    String publicKey = Base64.encodeBase64String(pair.getPublic().getEncoded());
    
    Map keyPair = new HashMap();
    keyPair.put("publicKey", publicKey);
    keyPair.put("privateKey", privateKey);
    
    return keyPair;
}
Source: RegistrationService.java:23-33

​
KeyExchangeService

Manages secure session establishment: 
public SystemResponse<KeyExchangeResponse> doKeyExchange() throws Exception {
    EllipticCurveUtils curveUtils = new EllipticCurveUtils("ECDH");
    KeyPair pair = curveUtils.generateKeypair();
    String privateKey = curveUtils.getPrivateKey(pair);
    String publicKey = curveUtils.getPublicKey(pair);
    
    // Create key exchange request with ECDH public key
    KeyExchangeRequest request = new KeyExchangeRequest();
    request.setClientSessionPublicKey(publicKey);
    // ... perform key exchange
}
Source: KeyExchangeService.java:14-32

​
Automatic key exchange

The middleware automatically handles key exchange before payment operations. The PaymentsService checks for valid session keys and performs key exchange when needed.
You don’t need to manually call key exchange before each payment—the middleware handles this automatically.

​
Response codes

Authentication operations return standard Phoenix response codes:
CodeMeaningAction
00ApprovedAuthentication successful
06ErrorCheck credentials and retry
96System errorContact support
Source: PhoenixResponseCodes.java

​
Best practices

Secure key storage

Store private keys securely and never commit them to version control

Rotate credentials

Update client secret after registration and rotate keys periodically

Daily key exchange

Perform key exchange at application startup or daily

Monitor sessions

Track session expiry and re-authenticate when needed

​
Next steps

Generate keys

Create your RSA key pair

Register client

Complete the registration process

Key exchange

Establish secure sessions

API reference

View authentication endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us