API Endpoints Overview

Relevant source files

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

• index.js
• payment.js
• common.js
• package.json
• README.md

This document provides a technical overview of the zalopay Node.js module, which serves as a wrapper for the ZaloPay API. The module simplifies the process of creating payment orders, querying their status, handling refunds, and verifying callbacks from the ZaloPay service. It encapsulates the necessary request signing, HTTP communication, and data handling logic.

The core of the module is the ZaloPay class, which acts as the main entry point for all interactions. It utilizes helper classes for payment-specific operations and common utilities like HMAC signature generation. The primary external dependencies are axios for HTTP requests, crypto-js for cryptographic operations, and moment for timestamp generation.

Sources: index.js, payment.js, common.js, package.json

Core Components and Configuration

The module is initialized by creating an instance of the ZaloPay class with a configuration object. This object contains the credentials and endpoint information required to communicate with the ZaloPay API.

Sources: index.js:5-12

Configuration

The constructor of the ZaloPay class expects a configuration object with the following properties:

Parameter	Type	Description
app_id	String	The application ID provided by ZaloPay.
key1	String	The first key used for signing API requests.
key2	String	The second key used for verifying callback integrity.
url	String	The base URL for the ZaloPay API endpoint.

Sources: index.js:6-10

Main Class Structure

The ZaloPay class orchestrates the functionality by composing other components.

This diagram shows the relationship between the main ZaloPay class and its helper classes Payment, Hmac, and Http.

Sources: index.js:5-19, payment.js:4-11, common.js:4-21

Authentication and Signature Generation

All requests to the ZaloPay API and callbacks from it are secured using HMAC (Hash-based Message Authentication Code) with SHA-256. The module abstracts this process into the Hmac utility class.

Sources: common.js:4-15

Request Signing (Hmac.compute)

Before sending a request to a ZaloPay API endpoint, a signature (mac) is generated. The Hmac.compute method is responsible for this.

The process is as follows:

1. The values of the request parameters are collected into an array.
2. The array elements are joined into a single string, separated by a pipe character (|).
3. An HMAC-SHA256 hash is computed on this string using the provided key (key1 for API requests).
4. The resulting hash is returned as a hexadecimal string.

This flowchart illustrates the HMAC computation process for signing API requests.

Sources: common.js:5-8, payment.js:20-22

Callback Verification (Hmac.verify)

When ZaloPay sends a callback to the merchant's server, its integrity is verified using the verifyCallback method on the ZaloPay instance. This method internally uses Hmac.verify.

The process is:

1. The Hmac.verify method re-computes the HMAC signature on the callback data using key2.
2. It then compares the newly computed signature with the mac string provided in the callback.
3. It returns true if they match, and false otherwise.

Sources: index.js:14-16, common.js:10-13

API Endpoints

The payment.js file contains the logic for interacting with the specific ZaloPay API endpoints. All methods return a Promise that resolves with the data from the API response.

Sources: payment.js

Create Order

This endpoint is used to create a new payment order.

• Method: createOrder(order)
• Endpoint: /v2/create
• HTTP Method: POST
• Signing Key: key1

The order object passed to the method contains all the necessary details for the transaction. The method automatically adds app_id and app_time, generates the mac signature, and sends the request.

// Example usage from payment.js
const data = {
    ...this.config,
    ...order,
    app_id: this.config.app_id,
    app_time: Date.now(),
};
const hmac = Hmac.compute([data.app_id, data.app_trans_id, data.app_user, data.amount, data.app_time, data.embed_data, data.item], this.config.key1);

Sources: payment.js:13-25

The following sequence diagram shows the flow for creating an order.

Get Order Status

This endpoint retrieves the status of a previously created order.

• Method: getOrderStatus(app_trans_id)
• Endpoint: /v2/query
• HTTP Method: POST
• Signing Key: key1

The method requires the app_trans_id of the order to query. It constructs the request payload, signs it, and sends it to the ZaloPay API.

Sources: payment.js:28-37

Refund

This endpoint initiates a refund for a completed transaction.

• Method: refund(params)
• Endpoint: /v2/refund
• HTTP Method: POST
• Signing Key: key1

The params object must contain details about the refund, such as zp_trans_id, amount, and description. The method generates a unique m_refund_id using the current timestamp.

Sources: payment.js:39-50

Get Refund Status

This endpoint retrieves the status of a refund request.

• Method: getRefundStatus(m_refund_id)
• Endpoint: /v2/query_refund
• HTTP Method: POST
• Signing Key: key1

The method requires the m_refund_id that was used to initiate the refund. It signs the request containing the app_id, m_refund_id, and a timestamp before sending it.

Sources: payment.js:52-61

Summary

The zalopay module provides a straightforward interface for developers to integrate ZaloPay payment processing into their Node.js applications. It handles the key API interactions for order creation, status checking, and refunds. A critical feature is its built-in, automated handling of HMAC-SHA256 request signing and callback verification, which simplifies security implementation and reduces the likelihood of errors. By exposing a clean, promise-based API, it abstracts away the complexities of direct HTTP communication and data formatting.

Sources: index.js, payment.js, common.js