Module: Payment System (Pay)

Relevant source files

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

• zheng-pay/zheng-pay-dao/src/main/java/com/zheng/pay/dao/model/PayInOrder.java
• zheng-pay/zheng-pay-dao/src/main/java/com/zheng/pay/dao/model/PayMch.java
• zheng-pay/zheng-pay-web/src/main/java/com/zheng/pay/web/controller/AlipayController.java
• project-datamodel/zheng.sql
• zheng-pay/pom.xml
• zheng-pay/zheng-pay-web/pom.xml
• zheng-admin/src/index.html

The zheng-pay module is a comprehensive payment management system within the zheng project. It is designed as a microservice to handle financial transactions, including income and expenditure orders, merchant management, and integration with third-party payment providers like Alipay. The module is a key component of the overall architecture, providing a centralized service for all payment-related functionalities.

The system is composed of several sub-modules, including a web interface for payment processing, a data access layer, an RPC API for inter-service communication, and an administrative backend. The administrative functions are integrated into the main zheng-admin dashboard, allowing for unified management alongside other systems like CMS and UPMS.

Sources: zheng-pay/pom.xml, zheng-admin/src/index.html:101-103, project-datamodel/zheng.sql:330-461

Architecture and Components

The zheng-pay module follows a modular, multi-layer architecture, typical of a microservice. The parent pom.xml defines the constituent sub-modules, each with a distinct responsibility.

Sources: zheng-pay/pom.xml:18-26

This diagram illustrates the modular structure of the zheng-pay system.

Module	Description	Source
zheng-pay-common	Contains common classes, constants, and utilities shared across the payment module.	zheng-pay/pom.xml:19
zheng-pay-dao	The Data Access Object (DAO) layer, responsible for database interactions and mapping to data models like PayInOrder and PayMch.	zheng-pay/pom.xml:20
zheng-pay-rpc-api	Defines the Remote Procedure Call (RPC) service interfaces, allowing other microservices to interact with the payment system.	zheng-pay/pom.xml:21
zheng-pay-rpc-service	The implementation of the RPC services defined in the zheng-pay-rpc-api module.	zheng-pay/pom.xml:22
zheng-pay-sdk	A client-side Software Development Kit (SDK) that can be used by other applications to easily integrate with the payment services.	zheng-pay/pom.xml:23
zheng-pay-web	The web layer, containing controllers that expose HTTP endpoints for payment initiation and callbacks, such as the AlipayController.	zheng-pay/pom.xml:24
zheng-pay-admin	The administration interface for managing the payment system, integrated into the central zheng-admin application.	zheng-pay/pom.xml:25, zheng-admin/src/index.html:33

Database Schema

The database schema for the payment module is defined in zheng.sql and includes tables for managing merchants, payment vendors, orders (both incoming and outgoing), and various configurations.

Sources: project-datamodel/zheng.sql:330-461

The following Entity-Relationship diagram shows the relationships between the main tables in the payment schema.

Key Tables

pay_mch

Stores information about merchants using the payment system.

Column	Type	Description
pay_mch_id	int	Primary Key, auto-increment.
mch_id	varchar(20)	Merchant ID string.
name	varchar(20)	Merchant name.
reqKey	varchar(50)	Key for signing outgoing requests.
resKey	varchar(50)	Key for verifying incoming responses.
Sources: project-datamodel/zheng.sql:368-375

pay_vendor

Stores details about third-party payment providers.

Column	Type	Description
pay_vendor_id	int	Primary Key, auto-increment.
name	varchar(20)	Vendor name (e.g., "Alipay").
appid	varchar(50)	Application ID from the vendor.
appsecret	varchar(150)	Application secret from the vendor.
config	varchar(1000)	Additional JSON configuration.
Sources: project-datamodel/zheng.sql:438-445

pay_in_order

Represents an incoming payment order.

Column	Type	Description
pay_in_order_id	int	Primary Key, auto-increment.
pay_vendor_id	int	Foreign key to pay_vendor.
pay_mch_id	int	Foreign key to pay_mch.
amount	decimal(10,0)	The total amount of the order.
status	tinyint(4)	The status of the order (e.g., pending, paid).
ctime	bigint(20)	Creation timestamp.
Sources: project-datamodel/zheng.sql:332-342

Alipay Integration

The module integrates with Alipay for processing payments. This is handled by the AlipayController in the zheng-pay-web submodule, which depends on the Alipay SDK.

Sources: zheng-pay/zheng-pay-web/src/main/java/com/zheng/pay/web/controller/AlipayController.java, zheng-pay/zheng-pay-web/pom.xml:21-26

API Endpoints

The AlipayController exposes endpoints for initiating payments and handling asynchronous notifications from Alipay.

Endpoint	Method	Description
/alipay/pay/pc	GET	Initiates a payment for desktop web browsers. Returns an HTML form that auto-submits to the Alipay gateway.
/alipay/pay/wap	GET	Initiates a payment for mobile web browsers (WAP). Returns an HTML form for the Alipay WAP gateway.
/alipay/notifyUrl	POST	The asynchronous notification URL that Alipay calls to inform the system about payment status changes. It performs signature verification.
Sources: zheng-pay/zheng-pay-web/src/main/java/com/zheng/pay/web/controller/AlipayController.java:39-83

Payment Flow (PC)

The following sequence diagram illustrates the process of initiating a PC-based payment.

Asynchronous Notification Handling

After a payment is processed, Alipay sends a notification to the /notifyUrl endpoint. The controller is responsible for verifying the authenticity of this notification before updating the order status.

This flowchart shows the logic for handling the notification.

The verification process uses the public key and other configuration details stored in property files to ensure the request is genuinely from Alipay.

Sources: zheng-pay/zheng-pay-web/src/main/java/com/zheng/pay/web/controller/AlipayController.java:70-82

Core Data Models

The DAO layer uses plain Java objects to model the database tables. These models are used throughout the application to represent payment-related entities.

PayInOrder

This class represents a record from the pay_in_order table.

Field	Type	Java Getter	Description
payInOrderId	Integer	getPayInOrderId()	The unique identifier for the income order.
payVendorId	Integer	getPayVendorId()	ID of the payment vendor (e.g., Alipay).
payMchId	Integer	getPayMchId()	ID of the merchant receiving the payment.
amount	Long	getAmount()	The total amount of the order.
status	Byte	getStatus()	The current status of the payment.
ctime	Long	getCtime()	The creation timestamp of the order.
Sources: zheng-pay/zheng-pay-dao/src/main/java/com/zheng/pay/dao/model/PayInOrder.java

PayMch

This class represents a merchant account from the pay_mch table.

Field	Type	Java Getter	Description
payMchId	Integer	getPayMchId()	The unique identifier for the merchant.
mchId	String	getMchId()	The public-facing merchant ID string.
name	String	getName()	The name of the merchant.
reqkey	String	getReqkey()	The key used for signing requests sent from the system on behalf of the merchant.
reskey	String	getReskey()	The key used for verifying responses or notifications for the merchant.
Sources: zheng-pay/zheng-pay-dao/src/main/java/com/zheng/pay/dao/model/PayMch.java

Conclusion

The zheng-pay module is a well-defined microservice that provides robust payment processing capabilities for the zheng platform. It features a clean, modular architecture with a clear separation of concerns, a normalized database schema for managing merchants and transactions, and a practical integration with third-party payment gateways like Alipay. Its design, including RPC APIs and a client SDK, facilitates easy integration with other services within the project's ecosystem.