Getting Started

This document provides a technical overview of the zalopay Go application, a command-line tool designed to interact with the ZaloPay payment gateway. The application supports creating payment orders and checking the status of existing orders. It is structured around a central configuration, distinct modules for payment operations, and common utility functions for tasks like cryptographic signing.

The core functionality is exposed via command-line flags, allowing the user to specify the desired action (create or getstatus). The application then constructs the appropriate request, signs it using HMAC-SHA256, sends it to the ZaloPay API, and prints the response.

Architecture Overview

The application is a command-line interface (CLI) that orchestrates calls to the ZaloPay API. Its operation is driven by command-line arguments and a central configuration file.

The overall program flow is as follows:

This diagram illustrates the main execution path, starting from configuration loading to executing a command and exiting.
Sources: main.go:16-36

Configuration

The application's behavior is controlled by a configuration structure defined in config/config.go. This configuration holds API endpoints and credentials necessary for communicating with ZaloPay.

// config/config.go:5-12
type Config struct {
	AppID            string `json:"appid"`
	Key1             string `json:"key1"`
	Key2             string `json:"key2"`
	CreateOrderURL   string `json:"createorderurl"`
	GetOrderStatusURL string `json:"getorderstatusurl"`
}

Sources: config/config.go:5-12

The configuration is loaded from a file (e.g., config.json) at startup.

Sources: config/config.go:5-12, main.go:17-21

Core Operations

The application supports two primary operations, determined by the --command flag: creating an order and getting an order's status.

Creating a Payment Order

This operation is triggered by running the application with --command=create. It constructs and sends a request to the ZaloPay CreateOrderURL.

The sequence of events for creating an order is as follows:

This diagram shows the interaction between the local application modules and the external ZaloPay API during order creation.
Sources: main.go:29-32, payment/payment.go:11-50

The request body for creating an order includes several fields, with a mac field for the signature. The signature is an HMAC-SHA256 hash of a concatenated string of specific request parameters, using Key1 from the configuration.

The data string for the HMAC signature is constructed as: appid|app_trans_id|app_user|amount|app_time|embed_data|item.

Sources: payment/payment.go:28

Getting Order Status

This operation is triggered by running the application with --command=getstatus and providing an app_trans_id via the --transid flag. It queries the ZaloPay GetOrderStatusURL.

The sequence for checking status is:

This diagram illustrates the flow for querying the status of a previously created transaction.
Sources: main.go:33-36, payment/payment.go:52-82

Similar to order creation, the request requires an HMAC signature. The data string for the status query signature is: appid|app_trans_id|key1.

Sources: payment/payment.go:62

Security

Security is primarily handled through HMAC (Hash-based Message Authentication Code) signatures to ensure the integrity and authenticity of API requests.

HMAC Signature Generation

A common utility function, HmacSHA256, is used to generate signatures for all outgoing API requests.

// common/common.go:9-13
func HmacSHA256(s string, key string) string {
	mac := hmac.New(sha256.New, []byte(key))
	mac.Write([]byte(s))
	return hex.EncodeToString(mac.Sum(nil))
}

This function takes a data string and a secret key, and returns the hex-encoded HMAC-SHA256 signature. This is a critical component for authenticating with the ZaloPay API.

Sources: common/common.go:9-13

The process for generating a signature is visualized below:

This flowchart breaks down the steps involved in creating the mac signature for API requests.
Sources: common/common.go:9-13, payment/payment.go:28, payment/payment.go:62