ZOLOZZOLOZDOCS

      Interact with Gateway

      #Overview

      ZOLOZ SaaS API is language independent, which means the customer could integrate the API with any programmatic language. However, the customer needs to fully understand ZOLOZ gateway protocol, properly create the request and handle the response. If the customer's project is written in Java, the customer could utilize an existing API SDK provided by ZOLOZ to integrate the API with ease, or else the customer could attempt to make his own implementation.


      In this chapter, we will firstly introduce how to utilize ZOLOZ API SDK, and then introduce how to use ZOLOZ help script to interact with ZOLOZ gateway, and finally introduce the advanced usage of ZOLOZ help script targeting on assisting the customer to validate his own implementation of the gateway protocol.

      #Utilize ZOLOZ API SDK

      #Integrate

      To utilize ZOLOZ API SDK, the customer only needs to introduce the library into the maven project by adding following dependency in the main POM file:

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

      #Usage

      copy
      // initialize OpenApiClient
      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>";
      
      OpenApiClient client = new OpenApiClient();  // construct with signature and encryption by default
      client.setHostUrl("https://sg-production-api.zoloz.com");
      client.setClientId(clientId);
      client.setMerchantPrivateKey(merchantPrivateKey);
      client.setOpenApiPublicKey(zolozPublicKey);
      //client.setSigned(false);     // signature (of response) validation can be turned off
      //client.setEncrypted(false);  // encryption can be turned off
      
      String response = client.callOpenApi(
          "v1.zoloz.authentication.test", 
          "{\"title\": \"hello\", \"description\": \"just for demonstration.\"}"
          );

      #Get the source code

      ZOLOZ API SDK has been open sourced on Github, please check the source code here.

      #PHP sample code

      we also provide a php sample code here.

      #Utilize ZOLOZ Helper Script

      #Get the script

      The helper script has been open sourced on Github, please check the source code here.

      #Usage

      copy
      ./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}'
      • 2188000123456789 is a dummy client Id, the customer should replace with his own one acquired from ZOLOZ portal.
      • merchant_private_key.pem is the private key generated at the customer's side, of which the corresponding public key has been registered in ZOLOZ portal.
      • 'MIIBIj...QIDAQAB' is the dummy content of the ZOLOZ public key, the customer should replace with his own one acquired from ZOLOZ portal.

      Other control options:

      • -e : disable encryption
      • -i : skip response signature validation

      #Own's Implementation Validation

      In case the customer would like to implement the gateway protocol by his own, it's important for the customer to be capable of validating his own's implementation.


      The helper script mentioned in previous section could help the customer a lot for validation purpose by adding some other options:

      • -v  or -vv : this will make the script more verbose and output much more intermediate data for validation.
      • -t <request time> : this will make the request adopt specified time instead of invoking time.
      • -k <AES128 key> : this will make the request adopt specified AES128 key to encrypt request content instead of a randomly generated one.


      Here's an live example of API call:

      8C8097C1-574E-4460-9EB2-7A54C9021A64.png


      The customer could validate as following steps:

      #1 Invoke the script to call the API

      copy
      ./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

      Here list some important options:

      • Enable verbose mode by adding -vv  option
      • Specify the AES128 key used to encrypt the request content with -k option (in the example we assume that the randomly generated AES128 key is 0x31313131313131313131313131313131)
      • Specify the request time directly with -t option (in the example we assume that the desired time is 2020-12-01 00:00:00 Singapore time)


      #2. Validate request encryption

      Confirm the final request content (“request body“) is the same with that of the customer's implementation:

      copy
      > request data length: 75
      >> request data: '{\n  "title": "hello",\n  "description": "This is just a demonstration."\n}'
      >
      > encryption: 1
      > aes128 key: 0x31313131313131313131313131313131
      > encrypted aes128 key: DcTqQNe9wc8HZByHRKZBM5HNAypDAWvHD8ugVxiQBdjosM4qzGPtI/sj58V48I0hYK/NLM3J1BcWf+TEXQzz7WkKl1+IVyF+2iYxe8Dx6UJeLNXFsHMKYWNiIdo4cKzkBL4lBEdJhZJwZtkYePq9dNAtXXWxBAsSDFDLejH1sTfBdpVUvGz0xUBZHeisNDS4Z1a/Em+RUtTZo7RqdGlBiUrSwVTOCcsrbaVk+LSP/GpVzbxMZU+FQ38/dvvHf6M7LlreRdyVIz4Rcz74sLOoEuYSg9ccTwp5modp04WRkCFYGI4FyMfZzam/hUWwe194LdUFpR+Dqp4GIiKVY5Vgjg==
      > urlencoded encrypted aes128 key: DcTqQNe9wc8HZByHRKZBM5HNAypDAWvHD8ugVxiQBdjosM4qzGPtI%2fsj58V48I0hYK%2fNLM3J1BcWf%2bTEXQzz7WkKl1%2bIVyF%2b2iYxe8Dx6UJeLNXFsHMKYWNiIdo4cKzkBL4lBEdJhZJwZtkYePq9dNAtXXWxBAsSDFDLejH1sTfBdpVUvGz0xUBZHeisNDS4Z1a%2fEm%2bRUtTZo7RqdGlBiUrSwVTOCcsrbaVk%2bLSP%2fGpVzbxMZU%2bFQ38%2fdvvHf6M7LlreRdyVIz4Rcz74sLOoEuYSg9ccTwp5modp04WRkCFYGI4FyMfZzam%2fhUWwe194LdUFpR%2bDqp4GIiKVY5Vgjg%3d%3d
      >
      > request body length: 108
      >> request body: 'Ve/sPNvLd1pDkl6gZURFrHS0mtzz2a0aCt927jgTarQbCBZYn2ikk8nrT5ymQ7YgqrqaOs2qnQW/3G/uVN+n6XJn5jVHTUfTTGJki/Gnqvs='

      NOTE:

      Most implementations of RSA encryption add random information to avoid possible attacks, so it is as expected that the customer's implementation produces different result for AES128 key encryption. However, the request content encryption is verifiable.


      #3. Validate request signature

      Confirm the request signature (urlencoded request signature“) is the same with that of the customer's implementation:

      copy
      >> request content to be signed: 'POST /api/v1/zoloz/authentication/test\n2188423368528034.2020-12-23T16:00:07+0800.Ve/sPNvLd1pDkl6gZURFrHS0mtzz2a0aCt927jgTarQbCBZYn2ikk8nrT5ymQ7YgqrqaOs2qnQW/3G/uVN+n6XJn5jVHTUfTTGJki/Gnqvs='
      > request signature: DXFMXcAw9+tx48c47ilhYY0yTBst0u4f2jLMBJl2H9dfPYiOwXH6EWTIyijGPUPVmWFK9pVx8fbUBeS2eIlRluxk+gKA/SuOIMg0VmQAyglIZjJKT7ecdYAqs90f76Pp3MM9LEyAeINlajd6lKyjJwN9YiNoRMoD1g78w7OOw8MbPY52hag0RoV1UGydC8ifK24amyu6+WVVy6XuLgcL1n/CaSk1urIUSFAm9Mq1xQ/ndz9VRHDLspbyfEt/2eML5vWoTyYxZxm9KYyMBjTVmZ9R0mbQMpFPXC0LA89PR8aqv6pCyoTpQ5c5ECrVhgIokdYs5Uf05P0APeShRar2/g==
      > urlencoded request signature: DXFMXcAw9%2btx48c47ilhYY0yTBst0u4f2jLMBJl2H9dfPYiOwXH6EWTIyijGPUPVmWFK9pVx8fbUBeS2eIlRluxk%2bgKA%2fSuOIMg0VmQAyglIZjJKT7ecdYAqs90f76Pp3MM9LEyAeINlajd6lKyjJwN9YiNoRMoD1g78w7OOw8MbPY52hag0RoV1UGydC8ifK24amyu6%2bWVVy6XuLgcL1n%2fCaSk1urIUSFAm9Mq1xQ%2fndz9VRHDLspbyfEt%2f2eML5vWoTyYxZxm9KYyMBjTVmZ9R0mbQMpFPXC0LA89PR8aqv6pCyoTpQ5c5ECrVhgIokdYs5Uf05P0APeShRar2%2fg%3d%3d


      #4. Validate response signature

      Confirm the signature (response signature“) could pass the signature validation of the customer's implementation against the target content (response content to be verified“):

      copy
      > response signature: OPiRd8jwCpP8M/Z+oNYjJLUU5zWd5XTk1XFQwX7+00AvIsAJpnP0YqgBfDrvlGuic38m164wAQUqKbFmSe6tNUFTmA+JZxnrwGSZmEbBuRzbB44h0Srgq+W6rC8oqntqjEWDVkdWzaayij5E/2ZAvsKKrTHPBjmECQ+jb78kwRo+jOlZ6rIOqSmKo2UL7XKsYhChKwrUe7nbwpBIg+fBEqMglCDCbMsSSsuavMpco1cwBtAXaZyPRmsqA27bTo9TSij65ovbeOxdZmBZqLXc7jiFKYFOJdLREXC022gLYALuUeP/PWecargIduHg5D+2+MXKiWYIhBZ7RYQe7Qtnew==
      > response time: 2020-12-23T08:01:04+0000
      >> response content to be verified: 'POST /api/v1/zoloz/authentication/test\n2188423368528034.2020-12-23T08:01:04+0000.Ve/sPNvLd1pDkl6gZURFrHS0mtzz2a0aCt927jgTarQbCBZYn2ikk8nrT5ymQ7YgqrqaOs2qnQW/3G/uVN+n6XJn5jVHTUfTTGJki/Gnqvs='
      > response signature verification result: 'Verified OK'


      #5. Validate response decryption

      Confirm the customer's implementation could decrypt the encrypted AES128 key (response encrypted symmetric key“) to the same AES128 key (response symmetric key“), and could decrypt the encrypted response content (response body“) to the same plain content (response content“).

      copy
      >> response body: 'Ve/sPNvLd1pDkl6gZURFrHS0mtzz2a0aCt927jgTarQbCBZYn2ikk8nrT5ymQ7YgqrqaOs2qnQW/3G/uVN+n6XJn5jVHTUfTTGJki/Gnqvs='
      
      > response encrypted symmetric key: I6dJGifO9pwTN26uoeET/T/aF8sDVBjnZY0dLaQu5WVbIbZTHEabGg8810N1tJGvbYtWjcJmM1XwKlOieLtVMElPgEpfQ3H3hrFotBpJM5qkYRaUKnJIQpWJSm5fPP4Pr+Lye2M+uVjkieNvTGe36OhBWOfxuhfo70x4jMENXHj2QuEP0JLu0peQBaoMKh/0C47fCQgijBrjcG0ON3eUe4jTvGQ5t00dFKhVmOnnHrP4zOFA6nfgGV4+T702fGxgIoq2CByT+hEWqvVXsEgZWzLse0RDcBjZ/ValRAxQYNuKP8ZzUNGiUt5GlyRmMi4aB69oFTx65Ey//5UXAxFvpg==
      > response symmetric key: 0x31313131313131313131313131313131
      > response content length: 72
      >> response content: {
      >>   "title": "hello",
      >>   "description": "This is just a demonstration."
      >> }