To ensure secure message transmission between your business and ZOLOZ services, you need to obtain the appropriate API credentials before connecting to the ZOLOZ gateway. These credentials are used for signing, verifying, encrypting, and decrypting messages.

ZOLOZ supports two connection methods to its gateway: public/private key and AK/SK. The API credentials required for each method differ:

• Public/Private Key : Prepare Customer ID, ZOLOZ transaction public key, merchant transaction public key, and merchant transaction private key.
• AK/SK : Prepare Customer ID, Access Key, and Secret Key.

For details on the differences between the two connection methods, see the Overview of Interacting to the ZOLOZ Gateway.

Before you begin

• Study the information in Gateway Protocol Overview 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 Set up your ZOLOZ portal account.

Get API credentials in the ZOLOZ portal

Public/Private Key Access

About the task

When connecting to the ZOLOZ gateway using the public/private key method, you must prepare the following API credentials to ensure secure data transmission.

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.

Get API Credentials

If you are connecting to the ZOLOZ gateway using the public/private key method, you can refer to the following steps to get API credentials.

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.
  

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

Create Merchant Transaction Key Pair

The following outlines the methods for automatically generating and manually creating a merchant transaction key pair. You can choose one method for creation.

Note: Whether you automatically generate or manually create the merchant transaction key pair, you must register the merchant transaction public key in the ZOLOZ portal.

Automatically Generate Merchant Transaction Key Pair

1. On the API Key page, click Auto-generate to automatically generate an RSA key pair for the merchant.

• The string corresponding to the merchant transaction public key will be automatically filled in the Merchant transaction public key field. Do not modify its content.

• The merchant transaction private key will automatically download to your local machine with the filename merchant_private_key.pem. Ensure you store it securely and do not share it with anyone.

Note: ZOLOZ does not store the merchant transaction private key, and the ZOLOZ team will never ask you to provide it.

2. Click the Submit button to register the merchant transaction public key in the ZOLOZ portal. Please note that if you forget to click, the registration process will not take effect.

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. Please note that if you forget to click, the registration process will not take effect.

AK/SK Access

When connecting to the ZOLOZ gateway using the AK/SK method, you need to prepare an Access Key (AK) and a Secret Key (SK) for message signing and signature verification. For more details, see AK/SK Management.