Interact with the ZOLOZ gateway
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>
<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.
//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
//Set the name of authentication test API
String apiName = "v1.aml.analyze";
//Set the request, a simple JSON object
String request = "{\"bizCode\":\"TEST\",\"extendData\":{\"certName\":\"test\",\"gender\":\"male\",\"nationality\":\"u\"},\"tenantID\":\"TEST\",\"tntInstID\":\"GLOBAL\"}";
//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
{
/**details for the hit**/
"hitResults":[
{
"reason":"{
"date":"2021/04/01",
/**screening engine type**/
"engineType":"WISE_NEXT_SANCTION",
/** if is Financially Exposed Person */
"fep":-1,
/**ID for hit watchlist**/
"hitId":"FAWC51068",
/**命中类型，可以不使用该字段，使用下面的tag字段**/
"hitType":1,
/**screening matching score**/
"matchRate":100,
/**watchlist provider**/
"origin":"DOWJONES",
/**引擎扫描分组**/
"originCategory":"US",
/**传入参数**/
"paramMatch":"carrie lam",
/** 是否是政治敏感人物 */
"pep":1,
/**匹配名单详情**/
"record":{
/**地址信息**/
"addressList":[
{
"addressCity":"",
"addressCountry":"hk",
"addressLine":"The Peak",
"addressState":""
}
],
/**出生地**/
"birthPlace":[
{
"name":"Hong Kong"
}
],
/**名单类别**/
"category":"POLITICAL INDIVIDUAL",
/**国籍信息**/
"countryDetails":[
{
"countryType":"Resident of",
"countryValueList":[
{
"code":"hk"
}
]
},
{
"countryType":"Citizenship",
"countryValueList":[
{
"code":"hk"
}
]
}
],
"date":"2021/04/01",
/**出生日期**/
"dateDetails":[
{
"dateType":"Date of Birth",
"dateValueList":[
{
"day":"13",
"month":"May",
"year":"1957"
}
]
}
],
/**是否已过时**/
"deceased":"No",
"gender":"Female",
/**名单分组**/
"groups":[
"TEST"
],
/**名单ID**/
"id":"WC51068",
/**名单证件信息**/
"idNumberTypes":[
{
"idType":"Passport No.",
"idValueList":[
{
"idNotes":"HONG KONG",
"value":"test"
}
]
}
],
"keywords":[
"OFAC-HK-EO13936",
"OFAC"
],
/**别名**/
"nameDetails":[
{
"nameType":"Primary Name",
"nameValueList":[
{
"firstName":"test",
"surname":"test",
"titleHonorific":""
}
]
},
{
"nameType":"Also Known As",
"nameValueList":[
{
"firstName":"Yuet Ngor",
"surname":"CHENG"
}
]
},
{
"nameType":"Native Character Name",
"nameValueList":[
{
"language":"zh-CN",
"originalScriptNameList":[
"\xE6\x9E\x97\xE9\x83\x91\xE6\x9C\x88\xE5\xA8\xA5"
]
}
]
}
],
"origin":"WORLDCHECK",
"originId":"51068",
/**职位**/
"position":"Chief Executive of the Hong Kong Special Administrative Region",
/**子类别**/
"subCategory":"PEP N",
"type":"Person"
},
"recordBirthDays":[
"19570513"
],
"recordBirthPlace":"Hong Kong",
/**名单证件号**/
"recordIdentifyNo":"TEST",
/**匹配记录**/
"recordMatch":"LAM",
"recordNations":[
"hk"
],
"recordResCountries":[
"hk"
],
/**引擎tag信息**/
"tag":"GROUP1.PERSON_NAME",
/**名单类型 Individual：个人,Company：公司，Vessel:, Other：其他 **/
"type":"Individual"
}",
/**引擎扫描参数**/
"scanArgs":"[{\"groupName\":\"GROUP1\",\"requestArgMap\":{\"PERSON_NAME\":\"Li Yi\"},\"watchlistGroups\":[\"ALL_SANCTION_WATCHLIST\"]}]",
"scanTarget":"NOT_USED",
/**引擎扫描结论**/
"scanResult":"review"
}
],
"requestID":"2112121234141151",
"amlDecision":"ACCEPT",
"amlResultCode":"AML_CLEAN"
}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.