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
- 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 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.
API credential type
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
The private key is used for ZOLOZ to
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
The private key is used for you to
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.
Get API credentials in the ZOLOZ portal
- Log in to the ZOLOZ portal with your username and password, and navigate to the API Key configuration page as Figure 1 shows.
- Copy the "Client ID" string and save it in your local workspace for the later use.
- Copy the "ZOLOZ transaction public key" string and save it in your local workspace for the later use.
- 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.
- 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.