The ZOLOZ API is independent of programming languages and exposed by the ZOLOZ gateway service. Before you integrate the ZOLOZ API, you must make sure that the ZOLOZ gateway service is accessible. This topic describes how to use a Java library or the ZOLOZ helper script to integrate the ZOLOZ API. This topic also describes how to use the ZOLOZ helper script to verify the implementation of a gateway protocol that you specify.

Prerequisites

• The ZOLOZ gateway service is implemented based on a gateway protocol. You are familiar with the ZOLOZ gateway protocol.

• The API credentials used to communicate with the ZOLOZ gateway service are obtained. For more information, see Obtain API credentials.

Integration methods

To integrate the ZOLOZ gateway, you can use a gateway protocol library provided by ZOLOZ or specify a gateway protocol.

• ZOLOZ provides multiple libraries. You can select a library based on your programming language and your environment.

• You can use a Java library if your programming language is Java. For more information, see the "Add a Java library" section of this topic.

• You can use a helper script if you want to call the ZOLOZ API in a shell environment. For more information, see the "Use a helper script" section of this topic.

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

Authentication test operation

In this example, the authentication test operation is called. The authentication test operation is a special API operation used for the authentication testing of various services. You can initiate an API request that contains a valid JSON object to call the authentication test operation. The operation returns a response that contains the same JSON object in the format of a JSON string. This is similar to the function of an echo command.

You must integrate the ZOLOZ gateway before you can call the authentication test operation. You can call other API operations with ease after you know how to call the authentication test operation.

Method 1: Use a gateway protocol library provided by ZOLOZ

Add a Java library

The Java libraries of ZOLOZ are published in the Maven Central Repository. This section describes how to use a public Java library to integrate the ZOLOZ gateway and call the ZOLOZ API.

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); 

You must replace the values of the following parameters in the code with actual values. For more information about how to obtain the values of the clientId, zolozPublicKey, and merchantPrivateKey parameters, 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 shell environment that supports Portable Operating System Interface (POSIX) standards 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 sample values used in the preceding code are for reference only. In actual scenarios, you must replace the values of the following parameters with 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 merchant transaction private key. In the preceding code, merchant_private_key.pem is used as a sample value. You must replace the sample value with the actual path of the merchant transaction private key.

• -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.

In addition to the preceding parameters, you can add the following parameters based on your requirements:

• -e: disables encryption.

• -i: skips signature validation for the response.

Method 2: Use the specified gateway protocol

You can specify a gateway protocol to integrate the ZOLOZ API. Then, you can use the ZOLOZ helper script to verify the implementation of the specified gateway protocol. 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 by using the same request and add the following parameters to the script:

• -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 sample code provides an example on 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 details 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: In most cases, a random number of bits are added to the request that is encrypted based on the Rivest-Shamir-Adleman (RSA) algorithm to avoid possible attacks. When you encrypt the request by using the AES-128 algorithm, the output is different from the one encrypted by using the RSA algorithm. You can then check whether the content of the requests encrypted by using different algorithms is the same.

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 JAR package of a Java library and the ZOLOZ helper script are available on GitHub. You can obtain the source code from the following links:

• Java library

• ZOLOZ helper script