Local Development Setup

Relevant source files

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

• README.md
• package.json
• server.js
• config/config.js
• db/index.js
• routes/index.js
• controllers/payment.controller.js

This document outlines the necessary steps and components for setting up and running the zalopay project on a local development machine. The project is a Node.js application built with the Express framework, designed to integrate with the ZaloPay payment gateway.

The setup process involves configuring environment variables for ZaloPay API credentials and database connections, installing project dependencies via npm, and running the server. The application exposes API endpoints to handle payment creation and callbacks.

Prerequisites

Before starting, ensure you have the following installed:

• Node.js and npm: The runtime environment and package manager.
• MongoDB: The application uses MongoDB as its database, so a local or remote instance must be accessible.

Sources: package.json, db/index.js

Configuration

The application's behavior is controlled by environment variables, which are centralized in config/config.js. You must provide these variables in a .env file at the project root for the application to function correctly.

Sources: config/config.js:1-4

Environment Variables

The following table details the required environment variables:

Variable	Description	Default Value
PORT	The port on which the Express server will listen.	3000
MONGODB_URL	The connection string for the MongoDB database.	''
APP_ID	The Application ID provided by ZaloPay.	''
KEY1	The first key (Key1) provided by ZaloPay for signing requests.	''
KEY2	The second key (Key2) provided by ZaloPay for validating callbacks.	''
ENDPOINT	The API endpoint URL for the ZaloPay gateway.	''

Sources: config/config.js:6-11

Installation

1. Clone the repository to your local machine.

2. Navigate to the project's root directory.

3. Install the required npm packages by running:

   npm install
   

This command will download all dependencies listed in package.json, such as express, mongoose, cors, and axios.

Sources: package.json:11-21

Database Setup

The application connects to a MongoDB database using mongoose. The connection is managed in db/index.js.

The connection logic is as follows:

1. The MONGODB_URL is retrieved from the configuration.
2. The mongoose.connect() method is called to establish a connection.
3. Success or error messages are logged to the console.

// db/index.js
const mongoose = require('mongoose');
const config = require('../config/config');

async function connect() {
    try {
        await mongoose.connect(config.mongodb_url, {
            useNewUrlParser: true,
            useUnifiedTopology: true,
        });
        console.log('Connect successfully!!!');
    } catch (error) {
        console.log('Connect failure!!!');
    }
}

module.exports = { connect };

Sources: db/index.js:1-16

Running the Application

The package.json file defines scripts to run the application.

• For development (with auto-reloading):
  This command uses nodemon to automatically restart the server when file changes are detected.

  npm run dev
  

  Sources: package.json:8

• For production or standard execution:
  This command runs the server using node.

  npm start
  

  Sources: package.json:7

Upon a successful start, the server will connect to the database and begin listening for requests on the configured PORT.

Application Startup Flow

The following diagram illustrates the sequence of events when the application starts.

This flow is initiated in server.js, which orchestrates the database connection and Express server setup.

Sources: server.js:1-20, db/index.js:4-14

Application Architecture

The application follows a standard Model-View-Controller (MVC) pattern, with a clear separation of concerns between routing, business logic, and data access.

Component Interaction

This diagram shows how the main components of the application interact.

Request Handling Flow

When a client sends a request to create a payment, the application processes it as shown in the sequence diagram below.

This flow demonstrates how a request to /payment is handled by the payment.controller.js, which communicates with the external ZaloPay API to create an order and then redirects the client to the ZaloPay payment page.

Sources: routes/index.js:7, controllers/payment.controller.js:10-48

API Endpoints

The primary API endpoints are defined in routes/index.js.

Method	Path	Controller Function	Description
POST	/payment	createPayment	Creates a new ZaloPay payment order and returns a redirect URL.
POST	/callback	paymentCallback	Endpoint for ZaloPay to send callback notifications about payment status.
GET	/	(req, res) => ...	A simple health-check or root endpoint that returns "Hello World".

Sources: routes/index.js:5-8