ZOLOZ API Encryption Protocol Upgrade Notice

Dear Customer,

To continuously enhance data transmission security, ZOLOZ has upgraded the OpenAPI encryption protocol from AES-ECB to AES-GCM (RSA_AES_GCM). This upgrade is backward compatible on the server side, and existing clients are not required to upgrade. However, we recommend enabling GCM mode when onboarding new integrations or upgrading the SDK.

1. Upgrade Details

2. Why Upgrade

1. Stronger Security
   AES-GCM is an AEAD (Authenticated Encryption) algorithm that provides both confidentiality and integrity, effectively defending against tampering attacks. AES-ECB mode only offers basic encryption and is not recommended for production environments.
2. Industry Best Practice
   GCM mode is the mainstream choice in current TLS 1.3, financial payments, and identity verification scenarios.
3. Backward-Compatible Transition
   The server supports both ECB and GCM modes simultaneously. Legacy clients can continue running, while new clients are recommended to switch gradually.

3. Impact on Merchants

4. Official SDK Support

Using Java as an example, the latest ZOLOZ official SDK (v1.1.7) now supports RSA_AES_GCM:

• zoloz_api_sdk

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

The SDK automatically detects the encryption protocol based on the server response header and performs encryption/decryption accordingly.

5.AES-GCM Message Encryption and Decryption Introduction

For more information , please see AES-GCM message encryption and decryption

6. Fallback Plan

Using Java as an example, if you encounter any issues after updating to the latest version, you can roll back to v1.1.6 or explicitly disable the GCM feature by calling setUseGCM(false)

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

 public static OpenApiClient HK_DEV1_GCM_CLIENT = new OpenApiClient() {{
        setClientId(HK_DEV_CLIENT_ID);
        setOpenApiPublicKey(HK_DEV_OPEN_API_PUBLIC_KEY);
        setMerchantPrivateKey(HK_DEV_OPEN_MERCHANT_PRIVATE_KEY);
        setHostUrl(HK_DEV_HOST_1);
        setEncrypted(true);
        setUseGCM(false);
    }};

7. Frequently Asked Questions

Q1: Will existing clients continue to work?
Yes. The server will run both ECB and GCM modes simultaneously, so existing clients will not be interrupted.

Q2: Do I need to replace the merchant key?
No. The RSA key pair remains unchanged.

Q3: Will GCM affect API performance?
The impact is negligible. AES-GCM has hardware acceleration (AES-NI) on modern CPUs, and its encryption/decryption latency is comparable to ECB.

Q4: How can I confirm that I have switched to GCM?
If the algorithm field in the request header shows RSA_AES_GCM, the new protocol is in use.

8. Recommendation

• New integrations: We recommend using GCM mode directly.
• Existing integrations: We recommend switching to GCM during your next SDK upgrade.

If you have any questions, please contact ZOLOZ technical support.