Get API credentials ready for use

To ensure the message transmission security between your business and the ZOLOZ service, you need to ensure the API credentials are ready for message signing, signature validation, message encryption and decryption.

Before you begin

About the task

The following table shows the API credentials that are needed for message transmission security in terms of what they are and what they are used for.

API credential type

Description

Usage

Client ID

A unique identifier of your account

Used for identifying who sends the request. It must be included in the content to be signed for a request and the content to be validated for a response.

ZOLOZ transaction key pair

The key pair that is provided by ZOLOZ, which consists of a public key and a private key.

The public key is used for you to

  • encrypt your request that is sent to ZOLOZ
  • validate the signature of the response from ZOLOZ

The private key is used for ZOLOZ to

  • decrypt the request that is sent from you
  • sign the response that is returned to you

Client transaction key pair

The key pair that is provided by you, which consists of a public key and a private key.

The public key must be submitted to ZOLOZ portal and is used for ZOLOZ to 

  • validate the signature of the request that is sent from you
  • encrypt the response that is returned to you

The private key is used for you to

  • sign your request that is sent to ZOLOZ
  • decrypt the response from ZOLOZ

The Client ID and ZOLOZ transaction key pair are generated by ZOLOZ when your portal account is created. You can obtain the Client ID and the ZOLOZ transaction public key from the ZOLOZ portal.

The client transaction key pair can be configured in the following two methods:

  • Use the ZOLOZ portal to automatically generate a key pair for you. This method is recommended when you want to quickly set up message transmission security, for example, for the testing purpose.
  • Manually generate the key pair by yourself and fill in the public key on ZOLOZ portal. This method is recommended for production setup such that no one but you knows the private key.

This task includes the following two parts:

    • Get the Client ID and ZOLOZ transaction public key
    • Generate the client transaction key pair and register the client transaction public key in ZOLOZ portal

Procedure

Get API credentials in the ZOLOZ portal

image.png

Figure 1

  1. Log in to the ZOLOZ portal with your username and password, and navigate to the API Key configuration page as Figure 1 shows.
  2. Copy the "Client ID" string and save it in your local workspace for the later use.
  3. Copy the "ZOLOZ transaction public key" string and save it in your local workspace for the later use.
  4. Click the Auto-generate button, a RSA key pair will be generated, among which
    • the public key string is automatically filled into the Client transaction public key field.

Note: Do not modify the content.

    • the private key string is automatically downloaded to your local workspace as a file called merchant_private_key.pem.

Note: ZOLOZ does not save the client transaction private key, and the ZOLOZ team never asks you for the client transaction private key anytime. Please keep the client transaction private key safe and don't share it with anyone else.

  1. Click the Submit button to register the Client transaction public key in the ZOLOZ system.

Manually generate a client key pair

You can manually generate a client transaction key pair by using the OpenSSL toolkit or the KeyPairGenerator Java class. Below are two examples:

Sample 1: using OpenSSL

copy
# Generate the private key, which will be used to sign your request.
# Note: this key cannot be directly used for Java. You need to transform the key to the PKCS8 format.
openssl genrsa -out priv_key_tmp.pem

# Transform the private key to the PKCS8 format if Java is used
openssl pkcs8 -topk8 -inform PEM -in priv_key_tmp.pem -outform PEM -nocrypt -out priv_key.pem 

# Generate the public key
openssl rsa -in priv_key_tmp.pem -pubout -out pub_key.pem 

# Generate the public key that is applicable to Java
cat pub_key.pem | grep -v "^\-" | tr -d "\n" | sed 's/%$//' > pub_key.base64

Sample 2: using Java

copy
KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");

SecureRandom secureRandom = new SecureRandom();
keyPairGenerator.initialize(2048, secureRandom);

KeyPair keyPair = keyPairGenerator.generateKeyPair();
Key publicKey = keyPair.getPublic();
Key privateKey = keyPair.getPrivate();

String publicKeyBase64 = Base64.getEncoder().encodeToString(publicKey.getEncoded());
String privateKeyBase64 = Base64.getEncoder().encodeToString(privateKey.getEncoded());

Once the public key is generated, you need to log in to the ZOLOZ portal, copy the public key string to the Client transaction public key field in the API Key configuration page, and click the Submit button to register the client transaction public key in the ZOLOZ system.