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

• Study the information in The gateway protocol and Message transmission security to understand the rules of creating an API request and handling a response with security considered.

• Ensure that you have an admin account for the ZOLOZ portal. For more information about how to set up an ZOLOZ portal account, see 2. Set up your ZOLOZ portal account.

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.

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 API credentials in the ZOLOZ portal: how to use the ZOLOZ portal to get the API credentials ready for use, including:

• 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

• Manually generate a client key pair: how to manually generate a client transaction key pair by yourself and register the client transaction public key in ZOLOZ portal.

Procedure

Get API credentials in the ZOLOZ portal

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.

5. 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

# 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

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.