Get Bank List Endpoint

Relevant source files

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

• api/gateway.js
• config/config.js
• utils/helper.js
• index.js
• package.json
• README.md

Introduction

The "Get Bank List" feature provides the functionality to retrieve a list of supported banks from the ZaloPay API. This is a server-side capability within a Node.js application that uses the Express framework. The core logic involves constructing a signed request, sending it to the ZaloPay gateway, and processing the response. This feature is essential for any part of the application that needs to present users with a choice of banks for payment.

The system relies on several key modules: a gateway for API communication, a configuration file for credentials, and a helper utility for cryptographic signing. The main application is built using Express, with dependencies such as axios for HTTP requests and crypto-js for generating HMAC signatures.

Sources: api/gateway.js, index.js:5-10, package.json:14, 18

System Architecture

The functionality is handled by a few distinct components within the Node.js application. The Express server acts as the host, but the primary logic is encapsulated in the gateway.js module. This module uses configuration from config.js and cryptographic functions from helper.js to communicate with the external ZaloPay API.

The following diagram illustrates the high-level architecture for retrieving the bank list.

This diagram shows that a client within the application calls the getBankList function. This function uses configuration and helper utilities to build and send a signed request via axios to the ZaloPay API, then returns the result.

Sources: api/gateway.js, config/config.js, utils/helper.js

Request Flow

The process of fetching the bank list follows a strict sequence to ensure the request is properly authenticated with the ZaloPay API. The authentication mechanism is based on an HMAC-SHA256 signature.

The sequence diagram below details the step-by-step interaction between the application's components and the ZaloPay API.

This flow demonstrates the creation of the request, from gathering configuration and generating a timestamp to signing the data and making the final HTTP POST call.

Sources: api/gateway.js:4-21, config/config.js, utils/helper.js

Key Components

Gateway Module (api/gateway.js)

This module is the core of the feature. It exposes the getBankList asynchronous function, which encapsulates all the logic for communicating with the ZaloPay getbanklist endpoint.

Key responsibilities:

• Reading application configuration (appid, key1, endpoint).
• Generating the current timestamp (reqtime).
• Constructing the data string for the HMAC signature.
• Calling the hmac.Hex utility to create the signature (mac).
• Sending the POST request with axios to the ZaloPay API.
• Returning the data portion of the ZaloPay response.

// File: api/gateway.js:4-21
const getBankList = async () => {
  const config = require("../config/config");
  const { getCurrentDate, hmac } = require("../utils/helper");

  let reqtime = getCurrentDate();
  let data = config.appid + "|" + reqtime + "|" + config.key1; // data for sign
  let mac = hmac.Hex(data, config.key1);

  let header = {
    "Content-Type": "application/x-www-form-urlencoded",
  };

  try {
    let result = await axios.post(
      config.endpoint + "getbanklist",
      qs.stringify({ appid: config.appid, reqtime, mac })
    );
    return result.data;
  } catch (error) {
    console.log(error);
  }
};

Sources: api/gateway.js:4-21

Configuration (config/config.js)

All necessary credentials and endpoints for the ZaloPay API are stored in this file. This centralization allows for easy management of environment-specific settings.

Parameter	Type	Description
appid	String	The application ID provided by ZaloPay.
key1	String	The first key used for generating the HMAC signature.
key2	String	The second key, used for other API callbacks (not used in getBankList).
endpoint	String	The base URL for the ZaloPay API gateway.

Sources: config/config.js:1-6

HMAC Signature Generation (utils/helper.js)

This utility file provides a helper object for cryptographic operations. The hmac.Hex function is used to create an HMAC-SHA256 signature, which is a critical part of authenticating requests to the ZaloPay API.

The signature is generated from a concatenated string of the appid, a timestamp, and key1, separated by |.

// File: utils/helper.js:5-7
const hmac = {
  Hex: (data, key) => CryptoJS.HmacSHA256(data, key).toString(CryptoJS.enc.Hex),
};

The data string being signed is constructed as follows:

config.appid + "|" + reqtime + "|" + config.key1

Sources: utils/helper.js:5-7, api/gateway.js:9

API Request and Response

Request to ZaloPay

The getBankList function sends a POST request to the ZaloPay API endpoint .../v2/getbanklist. The body of the request is application/x-www-form-urlencoded and contains the following parameters.

Parameter	Type	Description
appid	Number	The application ID from config.js.
reqtime	Number	The current timestamp in milliseconds.
mac	String	The HMAC-SHA256 signature of `appid

Sources: api/gateway.js:17-20

Response Structure

The getBankList function returns the data property from the axios response object. The exact structure of a successful response payload from ZaloPay is not defined within the repository's source code. However, based on the function's return statement, it is expected to be a JSON object containing the bank list. In case of an error, the error's response data is logged to the console.

Sources: api/gateway.js:20-23

Conclusion

The "Get Bank List" functionality is a well-defined and secure mechanism for fetching bank information from the ZaloPay payment gateway. It correctly implements an HMAC-based authentication flow, separates configuration from logic, and encapsulates the API interaction within a reusable getBankList function. This design makes it straightforward to integrate bank selection features into the broader application.