API Authentication

Ecentric’s Online Payments web service API is securely accessed using SSL/TLS with mutual authentication and is used to:

• establish a secure connection - using client and server certificates for mutual authentication
• encrypt the data transmitted between merchant applications and the web service API, preventing unauthorised access and protecting sensitive information from eavesdropping or tampering. This encryption ensures the confidentiality and integrity of the data exchanged over the API.

Client Certificate

A digital client certificate is an electronic file that provides a stamp of authenticity and is obtained from a trusted Certificate Authority (CA). It establishes the identity of the certificate owner and provides access to their public key.

Each client certificate is unique and contains a number of important elements including:

• Public key of the client
• Unique (or distinguished) name of the client
• Date from which the certificate is valid
• Expiry date of the certificate
• Name of the Certificate Authority (CA) that issued the certificate
• Digital signature (also known as a thumbprint) of the issuing CA - used by the server to validate the certificate

---

Merchant Requirements

Merchants using the API web service are required to:

1. obtain a client certificate from a trusted CA
2. provide Ecentric with:
   • certificate digital signature (thumbprint)
   • expiry date
3. attach the client certificate to API web service transaction requests

📘

Note:

• The certificate contains the device details so it is important to obtain the certificate from the Certificate Authority (CA) using the same device where the merchant application is loaded.
• When obtaining a certificate, it is important to explicitly specify that the certificate is for client authentication, otherwise it is likely that the certificate will be issued as a server certificate (which is more common)

Client certificate authentication involves the following steps:

1. Client registration and certificate generation:
   The client (user's device or application) obtains a digital certificate from a trusted Certificate Authority (CA) which contains its public key and other information.
   The client's private key is also generated and securely stored. This private key corresponds to the public key in the certificate and is used for cryptographic operations.

2. SSL/TLS handshake process:
   • Client initiates connection to the server and indicates its intent to establish a secure connection (“Client Hello”)
   • Server requests client certificate
   • Client sends digital certificate which includes the client’s public key and other identifying information
   • Server verifies the authenticity of the client certificate by:
     a. validating the CA's digital signature on the certificate, ensuring it is genuine and hasn't been tampered with
     b. checking that the certificate hasn't expired
   • Client’s private key is used to prove ownership of the public key presented in the certificate. This is done by digitally signing data (nonce) randomly generated by the server during the handshake process.

3. Client authentication:
   Once the client certificate has been verified, the client can access the web service API.