Configuring AppID and Keys
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The zalopay project integrates with the ZaloPay payment gateway. A critical aspect of this integration is the configuration of the application identifier (AppID) and cryptographic keys. These credentials are essential for authenticating requests sent to ZaloPay and for verifying the integrity of callbacks received from it. The AppID uniquely identifies the merchant's application, while two separate keys (key1 and key2) are used for generating request signatures and verifying callback signatures, respectively.
This system is designed around a central configuration file that supplies these credentials to different parts of the application, primarily the payment routing and cryptographic helper modules. Proper configuration is the foundation for all secure communication with the ZaloPay API.
Sources: config.js, router/payment.js, helper/crypto.js
Core Configuration
The application's credentials and API endpoint are centralized in the config.js file. This file exports an object containing all necessary values for interacting with the ZaloPay gateway.
Sources: config.js
Configuration Parameters
The following table details the parameters defined in the configuration file.
| Parameter | Type | Description |
|---|---|---|
app_id | String | The unique application identifier provided by ZaloPay. Included in all API requests. |
key1 | String | The secret key used to generate the HMAC signature (mac) for outgoing payment creation requests. |
key2 | String | The secret key used to verify the HMAC signature (checksum) of incoming callbacks from ZaloPay. |
endpoint | String | The URL of the ZaloPay API endpoint for creating new orders. |
Sources: config.js:1-5
Configuration Flow
The configuration object is imported and utilized by the payment router to construct and send API requests.
This diagram shows that config.js provides essential credentials to both the payment router and the cryptographic helper.
Sources: router/payment.js:4, router/payment.js:45
Key Usage in Cryptography
The security of the ZaloPay integration relies on HMAC (Hash-based Message Authentication Code) signatures. The project uses two distinct keys for different stages of the payment flow, managed by the helper/crypto.js module.
Sources: helper/crypto.js
Key 1: Request Signing
key1 is used to sign the data for creating a new payment order. A specific string format is constructed from the order details, and then an HMAC-SHA256 signature is generated using key1. This signature is sent as the mac parameter in the request body, allowing ZaloPay to verify that the request is authentic and has not been tampered with.
The data string for the signature is a concatenation of several order fields, separated by |:
app_id|app_trans_id|app_user|amount|app_time|embed_data|item
Sources: router/payment.js:33-34, helper/crypto.js:4-6
Key 2: Callback Verification
key2 is used to verify the authenticity of incoming server-to-server callbacks from ZaloPay. When a payment status changes, ZaloPay sends a POST request to the application's /callback endpoint. This request contains a JSON string and a mac (checksum). The application uses key2 to generate its own HMAC signature from the received JSON data and compares it to the mac provided by ZaloPay. A match confirms the callback is legitimate.
The verify function in helper/crypto.js encapsulates this logic.
// helper/crypto.js:8-10
const verify = (checksum, data, key) => {
return checksum === hmac(key, data);
};
Sources: router/payment.js:44-46, helper/crypto.js:8-10
Application in Payment Flow
The AppID and keys are central to the two main operations in the payment lifecycle: creating an order and handling the callback. These are managed in router/payment.js.
Sources: router/payment.js
Order Creation Flow
When a user initiates a payment, the server executes the following steps to create a ZaloPay order.
This sequence shows how app_id is part of the request payload and key1 is used via the Crypto helper to generate the mac signature before sending the request to the ZaloPay API endpoint.
Sources: router/payment.js:12-40
Callback Handling Flow
After the user completes the payment, ZaloPay sends a notification to the application's callback URL.
This diagram illustrates the callback verification process, where the server uses key2 to validate the incoming mac before processing the payment update. The server's ability to parse the JSON body of the callback is enabled by the body-parser middleware configured in index.js.
Sources: router/payment.js:42-55, index.js:7-8
Summary
The configuration of app_id, key1, and key2 is a foundational security measure for the zalopay application. The app_id serves as the public identifier, while the two separate keys enforce the integrity and authenticity of communication with the ZaloPay gateway. key1 secures outgoing requests to create payments, and key2 secures incoming callbacks, ensuring that the application only acts on legitimate, untampered information from ZaloPay. This two-key system provides a robust separation of concerns for request signing and response verification.
Sources: config.js, helper/crypto.js, router/payment.js