Production Checklist

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• index.js
• package.json
• common/config.js
• common/hmac.js
• services/order.js

This document provides a technical checklist for deploying and maintaining the ZaloPay integration service. It covers critical aspects such as configuration, dependencies, security, and API endpoints. The purpose is to ensure a stable, secure, and correctly functioning production environment.

This service is a Node.js application built with Express, designed to interface with the ZaloPay payment gateway. It handles order creation, status queries, and payment callbacks.

1. Dependency Management

Before deployment, ensure all required Node.js packages are installed and versions are verified. The application relies on several external packages for its core functionality.

Sources: package.json

Production Dependencies

The following packages are required for the application to run. They should be installed using npm install.

Package	Version	Description
axios	^0.21.1	Promise-based HTTP client for making requests to the ZaloPay API.
body-parser	^1.19.0	Node.js body parsing middleware for Express.
crypto	^1.0.1	Provides cryptographic functionality, used for HMAC signature generation.
express	^4.17.1	Web framework for Node.js used to create the server and API endpoints.
moment	^2.29.1	A JavaScript date library for parsing, validating, and formatting dates.
qs	^6.10.1	A querystring parsing and stringifying library.
websocket	^1.0.34	WebSocket implementation (though not used in the provided HTTP flow).

Sources: package.json:11-19

Development Dependencies

The following package is used for development and enables automatic server restarts on file changes. It should not be installed in a production environment.

Package	Version	Description
nodemon	^2.0.12	Utility that monitors for any changes and automatically restarts the server.

Sources: package.json:21-23

2. Application Configuration

All critical configuration values are centralized in common/config.js. These values MUST be reviewed and set correctly for the production environment. Do not use sandbox or test credentials in production.

Sources: common/config.js

Configuration Parameters

Key	Type	Description
app_id	String	The application ID provided by ZaloPay.
key1	String	The first key provided by ZaloPay, used for signing outgoing requests.
key2	String	The second key provided by ZaloPay, used for verifying incoming callbacks.
endpoint	String	The base URL for the ZaloPay API endpoint.

Sources: common/config.js:1-5

Example configuration:

// common/config.js:1-5
const config = {
  app_id: "2553",
  key1: "PcY4iZIKFCIdgZvA6ueMcMHHUbRLYjPL",
  key2: "kLtgPl8HHhgwk_3F1_8_V5fRroRJI_iP",
  endpoint: "https://sb-openapi.zalopay.vn/v2/create",
};

Note: The endpoint URL in the repository (https://sb-openapi.zalopay.vn/v2/create) points to a sandbox environment. This must be updated to the production ZaloPay URL before deployment.

3. Security

Security is primarily handled through HMAC (Hash-based Message Authentication Code) signatures to ensure data integrity and authenticity for both outgoing requests and incoming callbacks.

3.1. Outgoing Request Signing

All requests sent to the ZaloPay API must be signed using HMAC-SHA256 with key1. The hmac.js module provides the necessary function.

Sources: common/hmac.js, services/order.js:25

The signature is generated from a concatenated string of specific order parameters. The flow is as follows:

This diagram illustrates the process of generating the mac field for an outgoing API request.

Sources: services/order.js:10-25, common/hmac.js:4-6

3.2. Incoming Callback Verification

ZaloPay sends a POST request to the /callback endpoint to notify the service of a payment status change. The integrity of this callback must be verified using key2.

Sources: index.js:33-46, common/hmac.js:8-10

The verification process is as follows:

1. Receive the callback data (in JSON format) from ZaloPay.
2. Extract the mac field from the received data.
3. Generate a signature using the received data string and key2.
4. Compare the generated signature with the mac field from the callback.
5. If they match, the callback is authentic. If not, it should be rejected.

This sequence diagram shows the interaction for verifying an incoming callback from ZaloPay.

Sources: index.js:33-46, common/hmac.js:8-10

4. API Endpoints

The application exposes three main HTTP endpoints to handle the payment lifecycle. The server is configured to listen on port 3000.

Sources: index.js:10, 18-54

Method	Path	Description	Key Logic File
POST	/order	Creates a new payment order. It constructs the order data, signs it, and sends it to ZaloPay. Returns a redirect URL for the user to complete payment.	services/order.js
POST	/callback	The endpoint ZaloPay uses to send payment status updates. It verifies the callback's signature before processing.	index.js
GET	/order-status/:app_trans_id	Checks the status of an existing order by its app_trans_id.	services/order.js

Sources: index.js:18-54

Create Order Flow (/order)

This diagram shows the complete sequence for creating a new order.

5. Running in Production

The package.json file defines scripts for running the application.

• Development: npm run dev (uses nodemon)
• Production: npm start (uses node index.js)

For a production deployment, the npm start command must be used. Ensure the Node.js process is managed by a process manager like PM2, systemd, or Docker to handle restarts and logging.

Sources: package.json:7-9

The application uses console.log for logging information, including callback data and errors. For a production environment, it is highly recommended to replace console.log with a structured logging library (e.g., Winston, Pino) to enable better log management, filtering, and analysis.

Sources: index.js:23, 40, 42, 52, services/order.js:31

Summary

To deploy this ZaloPay integration service to production, an operator must:

1. Install Dependencies: Run npm install --production to install only the necessary packages.
2. Verify Configuration: Update common/config.js with the correct production app_id, key1, key2, and API endpoint.
3. Set Environment: Ensure the environment is secure and that the keys in config.js are protected.
4. Run Application: Use npm start to launch the server, preferably under a process manager.
5. Check Endpoints: Confirm that the server is listening on the correct port (default 3000) and that all endpoints are accessible as required.
6. Review Security: Understand the HMAC signing and verification flows to debug potential authentication issues.