Get Order Status Endpoint

Relevant source files

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

• index.js
• common/constant.js
• common/utils.js
• views/status.ejs
• package.json
• README.md

Introduction

The Get Order Status endpoint provides a mechanism to query the status of a transaction within the ZaloPay system. This server-side endpoint, exposed at /order_status, receives an application transaction ID from a client, constructs a signed request, and forwards it to the official ZaloPay API. It then receives the response from ZaloPay and renders the status information back to the client.

This process acts as a secure proxy, handling the sensitive task of generating the required mac (Message Authentication Code) signature for the API request. This prevents exposing secret keys to the client-side.

Endpoint Definition

The endpoint is defined within the main application server file. It listens for POST requests containing the transaction identifier.

• Path: /order_status
• Method: POST
• Description: Queries the status of a ZaloPay order using its app_trans_id.

Sources: index.js:98-118

Request and Response Flow

The process of checking an order's status involves the client, the application server, and the ZaloPay API.

The following sequence diagram illustrates the interaction between these components.

Request Payload and Signature Generation

To communicate with the ZaloPay API, the server must construct a specific payload and generate a mac signature to authenticate the request.

Sources: index.js:100-110, common/utils.js:1-3, common/constant.js:5-6

Payload for ZaloPay API

The server constructs a POST request to the ZaloPay query endpoint with the following parameters in its body:

Parameter	Type	Description	Source
app_id	String	The application's unique ID, retrieved from configuration.	config.app_id from common/constant.js
app_trans_id	String	The transaction ID to query. This is received from the client's request body (req.body.app_trans_id).	req.body.app_trans_id
mac	String	The HMAC-SHA256 signature generated to authenticate the request.	Generated using HmacSHA256 from common/utils.js

Sources: index.js:101-106, common/constant.js:5

MAC Signature Generation

A critical step is the generation of the mac signature, which validates the integrity and authenticity of the request to ZaloPay.

This diagram shows the signature generation flow.

The data string for the hash is formed by concatenating the app_id, app_trans_id, and the secret key1 with a | delimiter.

// index.js:104-105
const data = config.app_id + "|" + app_trans_id + "|" + config.key1; // app_id|app_trans_id|key1
const mac = CryptoJS.HmacSHA256(data, config.key1).toString();

The HmacSHA256 function is a simple wrapper around the crypto-js library's implementation.

// common/utils.js:1-3
const CryptoJS = require('crypto-js');
const HmacSHA256 = (message, key) => CryptoJS.HmacSHA256(message, key).toString();
module.exports = { HmacSHA256 };

Sources: index.js:104-105, common/utils.js:1-3, common/constant.js:6

API Communication and Response Handling

The server uses the axios library to send the signed POST request to the ZaloPay API endpoint.

API Request

The request is sent to the URL defined in config.endpoint.

// index.js:108-111
const result = {};
try {
    const { data: res } = await axios.post(config.endpoint, post_data);
    // ...

The config.endpoint is sourced from common/constant.js.

Constant	Value	Description
ZALOPAY_ENDPOINT	https://sb-openapi.zalopay.vn/v2/query	The ZaloPay API endpoint for querying orders.

Sources: index.js:109, common/constant.js:2

Response Rendering

Upon receiving a successful response from ZaloPay, the server renders the status.ejs view template, passing the response data directly to it. If the API call fails, the error is logged to the console.

// index.js:112-114
console.log(res);
return res.render("status", {
    title: "Get Order Status",
    ...res,
});

The status.ejs template then displays the key fields from the response, such as the return_code and return_message.

<!-- views/status.ejs:12-13 -->
<h2>Return Code: <%= return_code %></h2>
<h2>Return Message: <%= return_message %></h2>

Sources: index.js:112-116, views/status.ejs:12-13

Dependencies

The functionality relies on several key npm packages defined in package.json.

Package	Version	Usage
express	4.18.2	Web server framework for defining the /order_status route.
body-parser	1.20.2	Middleware to parse the incoming POST request body.
axios	1.4.0	Promise-based HTTP client to call the ZaloPay API.
crypto-js	4.1.1	Library used for generating the HMAC-SHA256 signature (mac).
ejs	3.1.9	Template engine to render the status.ejs view.

Sources: package.json:13-19, index.js:1-7

Summary

The "Get Order Status" feature is implemented as a single POST /order_status endpoint. It serves as a backend-for-frontend (BFF) that securely communicates with the ZaloPay API. Its primary responsibilities are to receive a transaction ID, generate the required mac signature using HmacSHA256, query the external ZaloPay endpoint, and render the result in a user-friendly HTML page. This architecture ensures that sensitive credentials like key1 are never exposed to the client.