Quick Start Tutorial

Relevant source files

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

• README.md
• example/python/create_order.py
• example/python/query_order.py
• example/python/refund.py
• common/hmac.py
• payment/views.py

This tutorial provides a guide for developers to integrate with the ZaloPay payment system using the provided Python examples. The scope of this document covers the essential payment flow: creating a payment order, querying the status of an order, and processing a refund.

The process relies on secure communication with the API, which is achieved through HMAC request signing. The following sections will detail the signing mechanism and the step-by-step process for handling transactions.

Core Concepts: Request Signing

All API requests to the ZaloPay system must be authenticated using an HMAC (Hash-based Message Authentication Code) signature. This ensures the integrity and authenticity of the request data. The signature is generated using a secret key provided by ZaloPay.

Sources: common/hmac.py, example/python/create_order.py:27-28

HMAC Generation

The signature is computed using the Hmac.compute method, which takes the algorithm (e.g., HmacAlgorithm.HMAC_SHA256), the secret key, and the data string as input. The data string is a concatenation of specific fields from the request payload, separated by |.

The following diagram illustrates the HMAC signature generation flow.

The core logic for this is found in common/hmac.py:

# common/hmac.py:10-13
class Hmac:
	@staticmethod
	def compute(algorithm, key, data):
		return hmac.new(key.encode(), data.encode(), algorithm).hexdigest()

This static method takes the algorithm, key, and data to produce a hexadecimal digest which serves as the signature.

Payment Flow

The primary payment flow consists of three main actions: creating an order, querying its status, and optionally, refunding the payment. The Python examples in the example/python/ directory demonstrate how to perform these actions.

Sources: example/python/

Step 1: Creating a Payment Order

To initiate a payment, the client application must first create an order. This is done by sending a POST request to the /api/createorder endpoint with the necessary order details and a valid MAC signature.

Sources: payment/views.py:11-14, example/python/create_order.py:33

Create Order Parameters

Parameter	Description	Example Value
app_id	The application's unique ID.	2553
app_trans_id	A unique transaction ID generated by the application.	230321_2553_1679393221932
app_user	The user initiating the transaction.	demouser
amount	The transaction amount.	50000
app_time	The timestamp of the transaction request in milliseconds.	1679393221932
embed_data	JSON string for extra data, like redirect information.	{"redirecturl": "https://google.com/"}
item	JSON string representing the items in the order.	[{"itemid":"knb","itemname":"kim nguyen bao"}]
description	A description of the transaction.	ZaloPay Integration Demo
bank_code	Code for the selected bank or payment method.	"" (empty for ZaloPay wallet)
mac	The HMAC signature for the request.	(Generated dynamically)

Sources: example/python/create_order.py:15-26

Create Order Sequence

The client application constructs the request, generates the MAC signature, and sends it to the ZaloPay API. The API validates the request and returns an order URL.

Step 2: Querying Order Status

After an order is created, its status can be checked using the /api/queryorder endpoint. This is useful for confirming if a payment was successful.

Sources: payment/views.py:17-20, example/python/query_order.py:22

Query Order Parameters

Parameter	Description	Example Value
app_id	The application's unique ID.	2553
app_trans_id	The transaction ID to query.	230321_2553_1679393221932
mac	The HMAC signature for the request.	(Generated dynamically)

Sources: example/python/query_order.py:12-15

The data for the MAC signature is formed by concatenating app_id, app_trans_id, and the secret key.

# example/python/query_order.py:16
data = config["app_id"] + "|" + app_trans_id + "|" + config["key1"] # app_id|app_trans_id|key1

Query Order Sequence

Step 3: Refunding a Transaction

A completed transaction can be refunded via the /api/refund endpoint. A successful refund request will be processed by ZaloPay.

Sources: payment/views.py:23-26, example/python/refund.py:27

Refund Parameters

Parameter	Description	Example Value
app_id	The application's unique ID.	2553
zp_trans_id	The ZaloPay transaction ID to be refunded.	23032100000123
amount	The amount to refund.	50000
description	A description for the refund.	ZaloPay Integration Demo
timestamp	The timestamp of the refund request in milliseconds.	1679394132349
m_refund_id	A unique refund ID generated by the merchant.	230321_2553_1679394132349
mac	The HMAC signature for the request.	(Generated dynamically)

Sources: example/python/refund.py:15-22

The MAC signature for a refund is generated from a string concatenating app_id, zp_trans_id, amount, description, and timestamp.

Sources: example/python/refund.py:23

Refund Sequence

API Endpoint Summary

The payment service exposes several endpoints for handling the payment lifecycle.

Method	Endpoint	View Function	Description
POST	/api/createorder	createorder	Creates a new payment order.
POST	/api/queryorder	queryorder	Queries the status of an existing order.
POST	/api/refund	refund	Initiates a refund for a transaction.
POST	/api/callback	callback	Endpoint for ZaloPay to send transaction status updates.

Sources: payment/views.py:11-29

Conclusion

This guide outlines the fundamental steps for integrating with the ZaloPay API. By following the Python examples, developers can implement a complete payment flow, including creating orders, verifying their status, and processing refunds. The cornerstone of this integration is the correct implementation of HMAC-SHA256 request signing to ensure secure communication with the ZaloPay platform. The provided code in example/python/ serves as a practical reference for these operations.

Sources: README.md, example/python/