Project Goals and Scope

Relevant source files

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

• gateway/gateway.go
• main.go
• common/hmac.go
• common/utils.go
• README.md
• go.mod

This project, zalopay, is a Go language software development kit (SDK) designed to facilitate integration with the ZaloPay payment gateway. The primary goal is to abstract the complexities of the ZaloPay API, providing a simplified interface for developers to perform key payment operations. The scope of the SDK includes creating payment orders, checking the status of existing orders, and retrieving a list of supported banks.

The project is structured into a core gateway package, which contains the main logic for API interaction, and a common package for shared utilities like cryptographic signing. An example implementation in main.go demonstrates how to use the SDK within a web application context.

Sources: README.md, go.mod:1, gateway/gateway.go, main.go

Core Architecture: The ZaloPay Gateway

The central component of the SDK is the Gateway struct, which acts as the client for all interactions with the ZaloPay API. It holds the necessary configuration and provides methods for API calls.

Sources: gateway/gateway.go

Gateway Configuration and Initialization

To use the SDK, a Gateway instance must be created using the NewGateway function. This function takes a Config struct containing the credentials and endpoint required for API communication.

Field	Type	Description
AppID	string	The application ID provided by ZaloPay.
Key1	string	The first key used for signing requests (HMAC).
Key2	string	The second key, used for other potential purposes.
Endpoint	string	The base URL for the ZaloPay API endpoint.

Sources: gateway/gateway.go:14-25

The following class diagram illustrates the structure of the Gateway and its configuration.

Gateway Methods

The Gateway struct exposes several methods to interact with the ZaloPay API:

• CreateOrder(params map[string]interface{}): Creates a new payment order.
• GetOrderStatus(apptransid string): Retrieves the status of a previously created order using its transaction ID.
• GetBankList(): Fetches a list of banks supported by ZaloPay.

Sources: gateway/gateway.go:35, 66, 88

Payment Order Creation Flow

The most critical feature is the creation of a payment order. This process involves constructing a request payload, signing it with an HMAC signature, and sending it to the ZaloPay API.

Sources: gateway/gateway.go:35-64, common/hmac.go:8-13

Request Parameters

The CreateOrder method accepts a map[string]interface{} containing the order details. Key parameters include:

Parameter	Description	Source Code Reference
app_id	The application ID. Automatically added from the Gateway config.	gateway/gateway.go:38
app_trans_id	A unique transaction ID for the order, generated by the client application.	gateway/gateway.go:40
app_time	The timestamp of the request in milliseconds.	gateway/gateway.go:39, common/utils.go:6-8
app_user	The user initiating the transaction.	main.go:29 (example usage)
amount	The transaction amount.	main.go:31 (example usage)
description	A description of the order.	main.go:32 (example usage)
bank_code	The code for the selected bank.	main.go:33 (example usage)
mac	The HMAC signature of the request data. Automatically generated.	gateway/gateway.go:45-48, common/hmac.go:8-13

Sequence of Operations

The following diagram illustrates the sequence of events when CreateOrder is called.

Security: HMAC Signing

All requests to the ZaloPay API must be signed to ensure data integrity and authenticity. This project uses HMAC-SHA256 for this purpose.

Sources: common/hmac.go

HMAC Computation

The common.Compute function is responsible for generating the signature.

// common/hmac.go:8-13
func Compute(algorithm, data, key string) string {
	h := hmac.New(sha256.New, []byte(key))
	h.Write([]byte(data))
	return hex.EncodeToString(h.Sum(nil))
}

The signing process is as follows:

1. A data string is constructed by concatenating specific fields from the request payload in a predefined order (e.g., appid|apptransid|appuser|amount|apptime|embeddata|item).
2. This data string and the Key1 from the Gateway configuration are passed to the Compute function.
3. The function uses Go's standard crypto/hmac and crypto/sha256 libraries to generate the HMAC-SHA256 hash.
4. The resulting hash is hex-encoded and added to the request payload as the mac field.

Sources: gateway/gateway.go:45-48, common/hmac.go:8-13

Example Implementation

The main.go file provides a practical example of how to use the SDK. It spins up a simple HTTP server that creates a ZaloPay order when its root endpoint (/) is accessed.

Web Server Flow

The diagram below shows the logic within the example web application.

Code Snippet: Order Creation

This snippet from main.go shows the instantiation of the gateway and the call to CreateOrder.

// main.go:21-37
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    config := gateway.Config{
        AppID:    "2553",
        Key1:     "PcY4iZIKFCIdgZvA6ueMcMHHUbRLYjPL",
        Key2:     "kLtgPl8HHhfvMuDHPwKfgfsY4Ydm9eQ2",
        Endpoint: "https://sb-openapi.zalopay.vn/v2/create",
    }
    // ...
    params := map[string]interface{}{
        "app_user":    "demo",
        "amount":      50000,
        "description": "ZaloPay Integration Demo",
        "bank_code":   "zalopayapp",
    }

    g := gateway.NewGateway(config)
    result, err := g.CreateOrder(params)
    // ...
})

Sources: main.go:21-37