Troubleshooting Common Issues

Relevant source files

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

• README.md
• main.go
• payment/zalopay.go
• router/router.go
• config/config.go
• common/utils.go

This document provides guidance for troubleshooting common issues that may arise when using this ZaloPay integration service. It covers problems related to configuration, payment creation, order status checking, and callback handling. The solutions and explanations are based exclusively on the application's source code.

The service is a Go application using the Gin web framework to expose several API endpoints for interacting with the ZaloPay payment gateway. Understanding the flow of requests through the defined routes is key to diagnosing problems.

1. Configuration Errors

Incorrect configuration is a primary source of errors, often leading to authentication failures or an inability to connect to ZaloPay's services. All configuration is loaded from a config.yml file at startup.

Sources: config/config.go, main.go:13-15

1.1. Key Configuration Parameters

Ensure the following parameters in your config.yml are correct. The application will fail to start if this file is missing or cannot be parsed.

Parameter	Description	File Reference
ZaloPay.AppID	The application ID provided by ZaloPay.	config/config.go:10
ZaloPay.Key1	The first key provided by ZaloPay, used for signing order creation and status check requests.	config/config.go:11
ZaloPay.Key2	The second key provided by ZaloPay, used for validating incoming callback requests.	config/config.go:12
ZaloPay.Endpoint	The base URL for the ZaloPay API endpoint.	config/config.go:13
Server.Port	The local port on which the service will run.	config/config.go:6

Sources: config/config.go:5-14

1.2. Common Symptoms of Misconfiguration

• 401/Unauthorized Errors from ZaloPay: This often indicates an incorrect AppID or Key1.
• Callback MAC Verification Failure: This points to an incorrect Key2.
• Connection Timeouts: This could be due to an incorrect Endpoint URL or network connectivity issues.

2. Payment Creation Failures

Payment creation is initiated via a POST request to the /order endpoint. Failures can occur during request signing, communication with ZaloPay, or if the ZaloPay API returns an error.

Sources: router/router.go:12, payment/zalopay.go:27-72

2.1. Payment Creation Flow

The following diagram illustrates the process of creating a new payment order.

This diagram shows the payment creation flow, from the initial API call to the final response.
Sources: router/router.go:12, payment/zalopay.go:27-72

2.2. MAC Signature Mismatch

A common failure point is an incorrect MAC (Message Authentication Code) signature. ZaloPay uses this signature to verify the integrity and authenticity of the request.

The signature for order creation is an HMAC-SHA256 hash. The data string to be signed is constructed by concatenating several fields with a | separator.

Data String Format:
appid|apptransid|appuser|amount|apptime|embeddata|item

The HmacSHA256 utility function is used to generate the hash using Key1.

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

Sources: payment/zalopay.go:49-51, common/utils.go:9-12

Troubleshooting Steps:

1. Verify that the Key1 in your configuration is correct.
2. Log the exact string being passed to the HmacSHA256 function in payment/zalopay.go and manually verify its format and content.
3. Ensure all fields (appid, apptransid, appuser, amount, apptime, embeddata, item) are correctly populated and in the right order.

2.3. ZaloPay API Errors

If the request to ZaloPay is successful but the transaction is rejected, ZaloPay will respond with a JSON body containing return_code and return_message. The CreateOrder function checks if return_code is not equal to 1.

• return_code != 1: Indicates a failure. The return_message will contain the reason.
• return_code == 1: Indicates success. The response will contain the order_url for the user to complete the payment.

Troubleshooting Steps:

• Log the full response body received from ZaloPay within the CreateOrder function to inspect return_code and return_message.

Sources: payment/zalopay.go:64-71

3. Callback Handling Issues

After a user completes a payment, ZaloPay sends a POST request to the /callback endpoint defined in the embed_data of the original order.

Sources: router/router.go:13

3.1. Callback Validation Flow

The service must validate the incoming callback to ensure it is a legitimate notification from ZaloPay. This is done by verifying a MAC signature in the callback data.

This diagram shows the sequence of events during a ZaloPay callback, including the critical MAC validation step.
Sources: payment/zalopay.go:96-114, router/router.go:13

3.2. Callback MAC Verification Failure

The callback mac is validated using Key2. The data string for the signature is constructed from the data field of the callback payload.

Troubleshooting Steps:

1. Check Key2: Ensure the Key2 in your configuration matches the one provided by ZaloPay. This is the most common cause of callback validation failure.
2. Inspect Callback Data: The code expects a JSON body with a data field and a mac field. If the structure is different, parsing will fail. The current implementation logs the received data, which can be inspected for debugging.
3. Network Accessibility: The /callback endpoint of your service must be publicly accessible over the internet for ZaloPay's servers to reach it.

Sources: payment/zalopay.go:102-113

4. Order Status Check Failures

The service provides an endpoint POST /order/status/:app_trans_id to check the status of a previously created order.

Sources: router/router.go:14

4.1. Status Check Logic

The logic is similar to order creation. It requires building a data string, signing it with Key1, and sending it to ZaloPay.

• Endpoint: POST /query on the ZaloPay API.
• Data String Format: appid|apptransid|key1
• Key: Key1 is used for signing.

The GetOrderStatus function handles this logic. It takes an app_trans_id and returns the status from ZaloPay.

Sources: payment/zalopay.go:74-94

4.2. Common Issues

• Invalid app_trans_id: Ensure the transaction ID passed in the URL exists and is correct.
• MAC Signature Mismatch: As with order creation, an incorrect Key1 or a malformed data string will cause the request to be rejected. Verify the string appid|apptransid|key1 is constructed correctly.
• ZaloPay API Errors: Check the return_code and return_message from the ZaloPay response. A return_code other than 1 signifies an error. The current code does not explicitly handle these error messages, so logging the raw response is recommended for debugging.

Sources: payment/zalopay.go:82-89