Interact with the ZOLOZ gateway
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.
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.
- Introduce the library in your maven project by adding the following dependency to the POM file.
- Import the OpenApiClient class.
- 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.
For ZOLOZ gateway URL, please refer to "Understand environments and service endpoints"
- Make a call to the API.
Use the helper script
- Get the helper script.
- Run the script from any posix shell environment to make a call to ZOLOZ API.
-cspecifies 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.
-Pspecifies 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.
-Kspecifies 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.
-aspecifies the path of the API. In the snippet above, the authentication test API is specified for demonstration.
-dspecifies 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.
- Invoke your own implementation to call an API and keep a record of the process details, including:
- the request time used in your call
- the randomly generated AES key for request encryption
- the encrypted request content
- the request signature
- Invoke the helper script to call the same API with the same request and the following options added:
-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.
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
- Compare your process details that are recorded in Step 1 with the verbose output that is printed in Step 2.
- 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.
- 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).
- 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).
- 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)).
JAR and Scripts
The libraries are open sourced on Github. For source code, go to:
ZOLOZ Gateway URL
For different SaaS and environment, the gateway URL(s) are different. Please refer to "Understand environments and service endpoints"