Interact with the ZOLOZ gateway

2025-10-17 02:58

ZOLOZ APIs are language independent and exposed by a gateway service.
To integrate ZOLOZ APIs, please first ensure that you can interact with the ZOLOZ gateway service.

Before you begin

The gateway service is implemented based on the gateway protocol. Please refer to the information in The gateway protocol to understand ZOLOZ's gateway protocol rules.
Follow the instructions in Get API credentials ready for use to obtain the relevant API credentials used for later interactions with the gateway service.

About the task

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

ZOLOZ provides these libraries for you:

Java Library: use this library if your programming language is Java

This task introduces the step-by-step guide for integrating ZOLOZ APIs using the Java library.

About the authentication test API

For demonstration, this task uses the authentication test API.
The authentication test API is a special API that is not related to any specific ZOLOZ product. It is designed solely for authentication testing purposes. It accepts any valid JSON object, and simply responds with the same JSON object, similar to echo command.

Like the other APIs, the authentication test API is also built upon the gateway service. This means that once you successfully make a call to the authentication test API, integrating other APIs will be very easy.

Steps

Integrate ZOLOZ APIs using 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 into your Maven project by adding the following dependencies to the POM file.

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

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

Please refer here for the latest versions of the dependencies.

Import the OpenApiClient class

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

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

copy
//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 the ZOLOZ gateway URL, please refer to Understand environments and service endpoints.

Call the API

copy
//Set the name of authentication test API 
String apiName = "v3.aml.nss.screen";

//Set the request, a simple JSON object
String request = "{\"bizCode\":\"ONBOARDING_PERSON_DEFAULT\",\"person\":{\"personName\":\"peter\"},\"customerId\":\"test_customer\",\"subjectType\":\"PERSON\"}";

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

Receive a response from the API

copy
{
    "decision": "REVIEW", 
    "bizCode": "ONBOARDING_PERSON_DEFAULT", 
    "hitResults": [
        {
            "scanArgs": "[{\"disableSearch\":false,\"groupName\":\"GROUP1\",\"requestArgMap\":{\"BIRTHDAY\":\"19660510\",\"CITIZENSHIP\":\"\",\"PERSON_NAME\":\"John Doe\",\"ID\":\"\",\"GENDER\":\"\"},\"watchlistGroups\":[\"DEMO_PERSON_SANCTION\"]}]", 
            "scanResult": "review", 
            "hitReason": {
                "engineType": "SANCTION", 
                "hitType": "name_match", 
                "paramMatch": "John Doe", 
                "recordMatch": "John Doe", 
                "matchRate": 100, 
                "matchStrategy": "s_person_name_common_src_full_name_similar"
            }, 
            "hitRecord": {
                "id": "example_12345", 
                "origin": "DOWJONES", 
                "type": "Person", 
                "activeStatus": "Active", 
                "nameDetails": [
                    {
                        "nameType": "Primary Name", 
                        "nameValueList": [
                            {
                                "firstName": "John", 
                                "surname": "Doe"
                            }
                        ]
                    }
                ], 
                "descriptions": [
                    {
                        "description1": "3", 
                        "description2": "1"
                    }
                ], 
                "dateDetails": [
                    {
                        "dateType": "Date of Birth", 
                        "dateValueList": [
                            {
                                "day": "10", 
                                "month": "May", 
                                "year": "1966"
                            }
                        ]
                    }
                ], 
                "sanctionsReferences": [
                    {
                        "toDay": "10", 
                        "toMonth": "Sep", 
                        "toYear": "2019", 
                        "value": "Sanctioned for financial crimes"
                    }
                ], 
                "countryDetails": [
                    {
                        "countryType": "Citizenship", 
                        "countryValueList": [
                            {
                                "code": "example_country_code"
                            }
                        ]
                    }
                ]
            }
        }
    ], 
    "totalHits": 1, 
    "rcrrRiskLevel": "", 
    "eventId": "6728d09e2113b33b6cc7e47a361c****", 
    "result": {
        "resultCode": "SUCCESS", 
        "resultMsg": "success", 
        "resultStatus": "S"
    }
}

Resources

JAR and Scripts

Libraries are open-source on Github. For the source code, please go to:

ZOLOZ Gateway URL

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