Querying Order Status

Relevant source files

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

• api/controllers/order.controller.js
• api/routes/order.route.js
• api/services/order.service.js
• api/services/zalopay.service.js
• config/zalopay.config.js
• index.js
• README.md

The Querying Order Status feature provides a mechanism to check the status of a payment transaction with the ZaloPay gateway. This is essential for verifying if a payment was successful, is still pending, or has failed after a user has been redirected from the ZaloPay payment page. The system exposes a dedicated API endpoint that takes an application transaction ID and communicates securely with the ZaloPay backend to retrieve the latest status.

This process involves routing the request, calling the appropriate service logic, constructing a signed request to ZaloPay, and forwarding the response back to the client.

API Endpoint

The feature is exposed via a single GET endpoint. The server listens for order-related routes under the /order path prefix.

Sources: index.js:20

Method	Path	Description
GET	/order/status/:app_trans_id	Queries the status of a specific transaction.

Sources: api/routes/order.route.js:5

Path Parameters

Parameter	Type	Description
app_trans_id	String	The unique transaction ID generated by the application for the order.

Sources: api/routes/order.route.js:5, api/controllers/order.controller.js:25

Request Processing Flow

When a client sends a request to the query status endpoint, it passes through several layers of the application before a response is returned. The controller receives the request, calls the order service, which in turn uses the ZaloPay service to perform the actual query against the ZaloPay API.

The following diagram illustrates the sequence of operations for a status query.

ZaloPay Service Integration

The core logic for communicating with the ZaloPay gateway resides in the zalopay.service.js. This service is responsible for constructing the request payload, generating the required security signature, and making the HTTP POST request to ZaloPay's query endpoint.

Sources: api/services/zalopay.service.js

Status Query Implementation

The queryStatus method in ZaloPayService orchestrates the query. It takes the app_trans_id as input and performs the following steps:

1. Retrieves configuration details like app_id and key1.
2. Constructs the data string for the signature.
3. Generates an HMAC-SHA256 signature (mac).
4. Builds the POST request body.
5. Sends the request to the ZaloPay order_status_endpoint.

Sources: api/services/zalopay.service.js:46-61

Signature Generation

To ensure the integrity and authenticity of the request, ZaloPay requires a Message Authentication Code (MAC) to be included in the payload. This signature is generated by creating an HMAC-SHA256 hash of a specific data string using a secret key (key1).

The data string is a concatenation of the following fields, separated by a pipe (|) character:
app_id|app_trans_id|key1

The following diagram shows the signature generation flow.

Request and Response

The service sends a POST request to the ZaloPay API with the following payload.

Request Payload to ZaloPay

Field	Type	Description	Source
app_id	String	The application ID provided by ZaloPay.	config.app_id
app_trans_id	String	The application's unique transaction ID.	Function argument
mac	String	The HMAC-SHA256 signature for request integrity.	Generated from `app_id

Sources: api/services/zalopay.service.js:54

A successful response from ZaloPay contains the status of the transaction. The service then forwards this data back to the controller.

Example Successful Response from ZaloPay

Field	Type	Description
return_code	Number	1 for success, 2 for failure, 3 for pending.
return_message	String	A descriptive message about the transaction status.
sub_return_code	Number	A more detailed status code.
sub_return_message	String	A more detailed status message.
is_processing	Boolean	Indicates if the transaction is still being processed.
amount	Number	The transaction amount.
zp_trans_id	Number	The unique transaction ID generated by ZaloPay.

Sources: api/services/zalopay.service.js:58

Configuration

The behavior of the ZaloPay integration is controlled by a configuration file. The following parameters are used for the order status query feature.

Parameter	Description	Example Value
app_id	The application ID from ZaloPay.	2553
key1	The first secret key for HMAC generation.	PcY4iZIKFCIdgZvA68zU...
order_status_endpoint	The URL for ZaloPay's query status API.	https://sb-api.zalopay.vn/...

Sources: config/zalopay.config.js:3-6