The ZOLOZ API is language independent and exposed by a gateway service. To integrate the ZOLOZ API, you must firstly ensure you can interact with the ZOLOZ gateway service.

Before you begin

• The gateway service is implemented based on the gateway protocol. Study the information in The gateway protocol to understand the rules of which the ZOLOZ gateway protocol contains.
• Follow the instructions in Get API credentials ready for use to obtain the related API credentials which are used in the later interaction with the gateway service.

About the task

To interact with the gateway service, you can either integrate the libraries that implement the gateway protocol with ease, or implement the gateway protocol by yourself.

ZOLOZ provides multiple libraries for you to choose based on your programming language and environment:

• Java library: use this library when your programming language is Java.
• Helper script: use this shell script when you need to call ZOLZO APIs directly from shell. The ZOLOZ helper script also provides advanced usage for you to validate your own implementation.

This task introduces you how to integrate the ZOLOZ API by using the Java library or the ZOLOZ helper script. It also provides instructions of how to validate your own implementation of the gateway protocol by using the ZOLOZ helper script.

About the authentication test API

This task uses the authentication test API for demonstration. The Authentication test API is a special API that is not related to any particular product. It is designed for authentication testing purpose. It accepts any valid JSON object, and simply responds with the same JSON object, similar with echo command.

Like other APIs, the authentication test API is also built upon the gateway service, which means after you successfully make a call to the authentication test API, integrating other APIs would be very easy.

Steps

Integrate the ZOLOZ API with libraries

Use the Java library

The ZOLOZ Java library is published on the Maven central repository. The following steps demonstrate how to use the public Java library to interact with the gateway service and call an API.

1. Introduce the library in your maven project by adding the following dependency to the POM file.

<dependency>
    <groupId>com.zoloz.api.sdk</groupId>
    <artifactId>zoloz-api-sdk</artifactId>
    <version>1.0.2</version>
</dependency>

Please refer here for the latest version of the dependency.

2. Import the OpenApiClient class.

import com.zoloz.api.sdk.client.OpenApiClient;

3. Instantiate an OpenApiClient instance and configure the instance with the API credentials, including the Client ID, the ZOLOZ transaction public key, the encoded merchant transaction private key.

//Set proper values to following vairables
String clientId = "<Client ID>";
String zolozPublicKey = "<ZOLOZ's public key content encoded in base64>";
String merchantPrivateKey = "<The merchant's private key content encoded in base64>";

//Instantiate an OpenApiClient object with signature validation and encryption both enabled by default
OpenApiClient client = new OpenApiClient(); 
client.setHostUrl("<ZOLOZ gateway URL>");
client.setClientId(clientId);
client.setMerchantPrivateKey(merchantPrivateKey);
client.setOpenApiPublicKey(zolozPublicKey);
//NOTE: uncomment the following line if you want to skip signature validation for response
//client.setSigned(false);      
//NOTE: uncomment the following line if you want to disable encryption
//client.setEncrypted(false);  

For ZOLOZ gateway URL, please refer to "Understand environments and service endpoints"

5. Make a call to the API.

//Set the name of authentication test API 
String apiName = "v1.zoloz.authentication.test";

//Set the request, a simple JSON object
String request = "{\"title\": \"hello\", \"description\": \"just for demonstration.\"}";

//Call the API, the response is expected to be a JSON string of the same JSON object
String response = client.callOpenApi(apiName, request);

Use the helper script

1. Get the helper script.

# Download the script to local.
wget https://raw.githubusercontent.com/zoloz-pte-ltd/zoloz-api-script/master/zoloz.sh

# Allow the script to be executed.
chmod u+x zoloz.sh

2. Run the script from any posix shell environment to make a call to ZOLOZ API.

# Assume that zoloz.sh is in current working directory.
./zoloz.sh \
  -c 2188000123456789 \
  -P merchant_private_key.pem \
  -K 'MIIBIj...QIDAQAB' \
  -a /api/v1/zoloz/authentication/test \
  -d '{\n  "title": "hello",\n  "description": "just for demonstration."\n}'

• -c specifies your client Id. "2188000123456789" that is used in the snippet above is a dummy one. You need to replace it with the one that you obtained from the ZOLOZ portal.
• -P specifies your merchant private key. "merchant_private_key.pem" in the snippet above is the dummy file path of the private key. You need to replace it with the path of your real private key, of which the corresponding public key has been registered in the ZOLOZ portal.
• -K specifies the content of the ZOLOZ public key. 'MIIBIj...QIDAQAB' in the snippet above is the dummy content of the ZOLOZ public key. You need to replace it with the one that you obtained from the ZOLOZ portal.
• -a specifies the path of the API. In the snippet above, the authentication test API is specified for demonstration.
• -d specifies the content of the request.

Apart from the options listed above, you can also add the following options as required:

• -e : disable encryption
• -i : skip response signature validation

Validate your own implementation

If you implement the gateway protocol by yourself, it is strongly recommended you follow the instructions below to use the ZOLOZ helper script to validate your implementation.

1. Invoke your own implementation to call an API and keep a record of the process details, including:

1. the request time used in your call
2. the randomly generated AES key for request encryption
3. the encrypted request content
4. the request signature

2. Invoke the helper script to call the same API with the same request and the following options added:

• -v or -vv: use this option to print verbose information for the later validation.
• -t <request time>: use this option to specify the request time as the time when the API request is invoked in Step 1.
• -k <AES128 key>: use this option to specify the AES128 key as the key used in Step 1 to encrypt the request content.

The following example shows how to run the script.

./zoloz.sh \
  -c 2**************4 \
  -P merchant_private_key.pem \
  -K 'MIIBIj...QIDAQAB' \
  -a /api/v1/zoloz/authentication/test \
  -d '{
  "title": "hello",
  "description": "This is just a demonstration."
}' \
  -vv \
  -k 31313131313131313131313131313131 \
  -t 2020-12-01T00:00:00+0800

The following figure shows the verbose output of the API call process.

Figure 1. Verbose output of the API call by using the ZOLOZ helper script

3. Compare your process details that are recorded in Step 1 with the verbose output that is printed in Step 2.

1. Validate request encryption. Check whether your encrypted request content is the same with the one that is displayed in the request body filed in Figure 1(2).

Note：Usually the implementation of RSA encryption adds random information to avoid possible attacks, so it is as expected that your implementation produces a different result for AES128 key encryption. However, you can compare the request content encryption as it is verifiable.

1. Validate request signature. Check whether your request signature to be filled in the request header is the same with the one that is displayed in the urlencoded request signature field in Figure 1(3).
2. Validate response signature. Confirm whether the signature displayed in the response signature field in Figure 1(4) can pass the signature validation of your implementation against the target content, which is displayed in the response content to be verified field in Figure1(4).
3. Validate response decryption. Check whether your own implementation can decrypt the encrypted AES128 key (the response encrypted symmetric key field in Figure1(5)) to the same AES128 key (the response symmetric key field in Figure1(5)). And check whether your implementation can decrypt the encrypted response content (the response body field in Figure1(5)) to the same plain content (the response content field in Figure1(5)).

Resources

JAR and Scripts

The libraries are open sourced on Github. For source code, go to:

• Java library
• ZOLOZ helper script
  

ZOLOZ Gateway URL

For different SaaS and environment, the gateway URL(s) are different. Please refer to "Understand environments and service endpoints"