The ZOLOZ API is language-independent and exposed through the ZOLOZ gateway service. Before you integrate the ZOLOZ API, make sure that the ZOLOZ gateway service is accessible. You can use a Java library or the ZOLOZ helper script to integrate the ZOLOZ API, and use the helper script to verify a custom gateway protocol implementation.

Prerequisites

• You are familiar with the ZOLOZ gateway protocol.

• You have obtained the API credentials for communicating with the ZOLOZ gateway service. For more information, see Obtain API credentials.

Integration methods

You can integrate the ZOLOZ gateway by using a gateway protocol library provided by ZOLOZ or by implementing a custom gateway protocol.

• ZOLOZ provides libraries for multiple programming languages and environments.

• For Java projects, use the Java library. For more information, see the "Add a Java library" section of this topic.

• For shell environments, use the helper script. For more information, see the "Use a helper script" section of this topic.

• If you implement a custom gateway protocol, you can use the ZOLOZ helper script to verify your implementation. For more information, see the "Method 2: Use the specified gateway protocol" section of this topic.

Authentication test operation

The authentication test operation is a special API operation for verifying service authentication. You send a request that contains a valid JSON object, and the operation echoes the same JSON object back as a JSON string.

Integrate the ZOLOZ gateway before you call the authentication test operation. After you successfully call this operation, you can call other API operations in the same way.

Method 1: Use a gateway protocol library provided by ZOLOZ

Add a Java library

ZOLOZ Java libraries are published in the Maven Central Repository. Perform the following steps to integrate the ZOLOZ gateway and call the ZOLOZ API by using the Java library.

1. Integrate ZOLOZ SDK for Java.

   Add the following dependency to the pom.xml file of your project. This way, the Java library is added to your project. You can obtain the latest version of the dependency from GitHub.

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

2. Import the OpenApiClient class.

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

3. Instantiate and configure the OpenApiClient class.

// Assign proper values to the following variables:
String clientId = "<Client ID>";
String zolozPublicKey = "<ZOLOZ transaction public key encoded in Base64>";
String merchantPrivateKey = "<Merchant transaction private key encoded in Base64>";

// Create an OpenApiClient object with both signature validation and encryption 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 the response:
//client.setSigned(false); 
// Note: Uncomment the following line if you want to disable encryption:
//client.setEncrypted(false); 

Replace the following parameter values in the code with your actual values. For more information about how to obtain these values, see Obtain API credentials.

• clientId: the client ID.

• zolozPublicKey: the ZOLOZ transaction public key that is encoded in Base64.

• merchantPrivateKey: the merchant transaction private key that is encoded in Base64.

• setHostUrl: the URL of the ZOLOZ gateway. For more information about how to obtain the URL of the ZOLOZ gateway, see Select a site and an environment.

4. Call the authentication test operation.

// Specify the name of the authentication test operation. 
String apiName = "v1.zoloz.authentication.test";

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

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

Use a helper script

1. Obtain the ZOLOZ helper script.

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

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

2. Run the script in a POSIX-compatible shell environment to call the authentication test operation.

# For example, zoloz.sh is in the 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}'

The preceding sample values are for reference only. Replace the following parameters with your actual values. For more information about how to obtain the client ID and the ZOLOZ transaction public key, see Obtain API credentials.

• -c: the client ID.

• -P: the path to the merchant transaction private key file. Replace merchant_private_key.pem with your actual file path.

• -K: the ZOLOZ transaction public key.

• -a: the path used to call an API operation. In the preceding code, the authentication test operation is called.

• -d: the content of the request.

You can also use the following optional parameters:

• -e: disables encryption.

• -i: skips signature validation for the response.

Method 2: Use the specified gateway protocol

You can implement a custom gateway protocol to integrate the ZOLOZ API, and then use the ZOLOZ helper script to verify your implementation. Perform the following steps:

1. Use your implementation class to call an API operation and record the details of the API call.

   You must record the following information:

• The amount of time that is taken to call the API operation.

• The randomly generated key that uses the Advanced Encryption Standard (AES) algorithm to encrypt the request.

• The encrypted request.

• The signature of the request.

2. Use the ZOLOZ helper script to call the same API operation with the same request, and include the following parameters:

• -v or -vv: displays the details of the API call for later verification.

• -t <Request time>: the amount of time that is taken to call the API operation. Use the value recorded in Step 1.

• -k <AES128 key>: the key that uses the AES-128 algorithm to encrypt the request. Use the value recorded in Step 1.

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 output of the API call.

3. Compare the details recorded in Step 1 with the output details displayed in Step 2.

1. Verify the encrypted request.

   Check whether the content of the encrypted request is the same as the value of the request body parameter in the section marked with 2 in the preceding figure.

   Note: RSA encryption adds random padding to prevent attacks, so the RSA-encrypted output differs from the AES-128-encrypted output. Compare the AES-128-encrypted content to verify consistency.

2. Verify the signature of the request.

   Check whether the signature of the request that you enter in the request header is the same as the value of the urlencoded request signature parameter in the section marked with 3 in the preceding figure.

3. Verify the signature of the response.

   Check whether the signature displayed in the response signature parameter in the section marked with 4 in the preceding figure is consistent with the signature of the response by using your implementation class. The response content is displayed in the response content to be verified parameter in the section marked with 4 in the preceding figure.

4. Verify the decrypted response.

• Check whether the decrypted key is the same key encrypted based on the AES-128 algorithm by using your implementation class. The decrypted key is the value of the response symmetric key parameter, and the key encrypted based on the AES-128 algorithm is the value of the response encrypted symmetric key parameter in the section marked with 5 in the preceding figure.

• Check whether you can use your implementation class to decrypt the encrypted response that is displayed in the response body parameter in the section marked with 5 in the preceding figure to the same plaintext that is displayed in the response content parameter in the section marked with 5 in the preceding figure.

References

The Java library JAR package and the ZOLOZ helper script are available on GitHub:

• Java library

• ZOLOZ helper script