payment-module-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

QloApps Payment Module Development

QloApps 支付模块开发

Create payment gateway modules that extend

PaymentModule

using hooks-first architecture.

使用钩子优先架构创建继承自

PaymentModule

的支付网关模块。

Quick Commands

快速命令

bash

undefined

bash

undefined

Payment module structure

modules/qlopaymentname/ ├── qlopaymentname.php # Main PaymentModule class ├── controllers/front/ │ ├── payment.php # Payment confirmation page │ ├── validation.php # Order processing (offline) │ ├── callback.php # Payment callback (online) │ └── webhook.php # Payment webhook (online) ├── classes/ # Helper/Service classes ├── views/templates/ │ ├── front/payment.tpl # Payment option display │ └── hook/payment_return.tpl # Success/failure message └── LICENSE.md


Common operations:
- Create offline payment — See [payment-patterns.md](./reference/payment-patterns.md#offline-payments)
- Create online payment — See [payment-patterns.md](./reference/payment-patterns.md#online-payments)
- Setup API credentials — See [integration-api.md](./reference/integration-api.md)
- Process payment — See [controllers-transactions.md](./reference/controllers-transactions.md)
- Handle webhooks — See [integration-api.md](./reference/integration-api.md#webhook-management)

---


常见操作：
- 创建线下支付——参见[payment-patterns.md](./reference/payment-patterns.md#offline-payments)
- 创建线上支付——参见[payment-patterns.md](./reference/payment-patterns.md#online-payments)
- 设置API凭证——参见[integration-api.md](./reference/integration-api.md)
- 处理支付——参见[controllers-transactions.md](./reference/controllers-transactions.md)
- 处理Webhook——参见[integration-api.md](./reference/integration-api.md#webhook-management)

---

When to Use This Skill

何时使用本技能

Applies to:

Creating payment gateway integration
Adding payment method to QloApps
Integrating third-party payment processors
Building custom payment solutions

适用场景：

创建支付网关集成
为QloApps添加支付方式
集成第三方支付处理器
构建自定义支付解决方案

When NOT to Use

何时不使用

Feature modules →
```
module-development
```
skill
Statistics modules →
```
stats-module-development
```
skill

功能模块→使用
```
module-development
```
技能
统计模块→使用
```
stats-module-development
```
技能

Payment Module Types

支付模块类型

Type	Example	Controllers	API	Order State
Offline	Bankwire, Cheque	payment, validation	No	Awaiting Payment
Online	PayPal, Credit Card Gateways	payment, callback, webhook	Yes	Payment Accepted

Payment type constants (from

OrderPayment

```
PAYMENT_TYPE_ONLINE = 1
```
— Real-time processing (credit cards, PayPal)
```
PAYMENT_TYPE_PAY_AT_HOTEL = 2
```
— Payment on arrival (QloApps specific)
```
PAYMENT_TYPE_REMOTE_PAYMENT = 3
```
— Offline (bank transfer, cheque)

The

PaymentModule

base class also provides:

```
$validateOrderAmount
```
— When
```
true
```
(default),
```
validateOrder()
```
checks that the paid amount matches the cart total

类型	示例	控制器	API	订单状态
线下	银行转账、支票	payment, validation	无	待支付
线上	PayPal、信用卡网关	payment, callback, webhook	是	支付已确认

支付类型常量（来自

OrderPayment

）：

```
PAYMENT_TYPE_ONLINE = 1
```
— 实时处理（信用卡、PayPal）
```
PAYMENT_TYPE_PAY_AT_HOTEL = 2
```
— 到店支付（QloApps专属）
```
PAYMENT_TYPE_REMOTE_PAYMENT = 3
```
— 线下支付（银行转账、支票）

PaymentModule

基类还提供：

```
$validateOrderAmount
```
— 当设置为
```
true
```
（默认值）时，
```
validateOrder()
```
会检查支付金额是否与购物车总额一致

Skill Components

技能组成部分

Reference guides for each area of payment module development:

module-structure.md — Folder structure, mandatory files, install/uninstall, currency/country restrictions, payment hooks
payment-patterns.md — PaymentModule class, offline pattern, online pattern, advance payment, pattern selection
integration-api.md — Configuration forms, API credentials, sandbox/production, webhooks, authentication
controllers-transactions.md — Payment/validation/callback/webhook controllers, validateOrder(), transactions, refunds, order states, security

支付模块开发各领域的参考指南：

module-structure.md — 文件夹结构、必填文件、安装/卸载、货币/国家限制、支付钩子
payment-patterns.md — PaymentModule类、线下支付模式、线上支付模式、预付款、模式选择
integration-api.md — 配置表单、API凭证、沙箱/生产环境、Webhook、身份验证
controllers-transactions.md — 支付/验证/回调/Webhook控制器、validateOrder()、交易、退款、订单状态、安全

Quick Reference

快速参考

Offline Payment Checklist

线下支付检查清单

Create main module class (extends PaymentModule)
Set
```
payment_type = REMOTE_PAYMENT
```
Create payment.php controller (show confirmation page)
Create validation.php controller (create order)
Register payment hooks
Create payment.tpl template
Add configuration for payment details
Setup email template with instructions

创建主模块类（继承PaymentModule）
设置
```
payment_type = REMOTE_PAYMENT
```
创建payment.php控制器（显示确认页面）
创建validation.php控制器（创建订单）
注册支付钩子
创建payment.tpl模板
添加支付详情配置
设置包含支付说明的邮件模板

Online Payment Checklist

线上支付检查清单

Create main module class (extends PaymentModule)
Set
```
payment_type = ONLINE
```
Create configuration form (API keys, test/live mode)
Create payment.php controller
Create callback.php controller (handle return)
Create webhook.php controller (handle notifications)
Create helper/service classes for API
Implement API authentication
Setup webhook URL
Handle payment success/failure
Implement refund capability
Create transaction logging

创建主模块类（继承PaymentModule）
设置
```
payment_type = ONLINE
```
创建配置表单（API密钥、测试/生产模式）
创建payment.php控制器
创建callback.php控制器（处理返回）
创建webhook.php控制器（处理通知）
为API创建辅助/服务类
实现API身份验证
设置Webhook URL
处理支付成功/失败情况
实现退款功能
创建交易记录

Security Checklist

安全检查清单

Common Pitfalls

常见陷阱

Storing credit card data — Use tokenization; gateway handles card data, store only token.
Missing webhook signature verification — Always verify webhook signatures from gateway.
No test/live mode separation — Separate test and live API keys, mode switcher in config.
Creating order before payment confirmation — Offline: use "Awaiting Payment" state. Online: create order only after success callback/webhook.
Missing advance payment check — Always check
```
$cart->is_advance_payment
```
and use
```
Cart::ADVANCE_PAYMENT
```
for total calculation.

存储信用卡数据——使用令牌化；由网关处理卡数据，仅存储令牌。
缺少Webhook签名验证——始终验证来自网关的Webhook签名。
未区分测试/生产模式——分开测试和生产API密钥，在配置中添加模式切换器。
支付确认前创建订单——线下支付：使用“待支付”状态。线上支付：仅在成功回调/Webhook后创建订单。
缺少预付款检查——始终检查
```
$cart->is_advance_payment
```
，并使用
```
Cart::ADVANCE_PAYMENT
```
计算总额。

Reference Modules

参考模块

Module	Type	Key Concepts
`modules/bankwire/`	Offline	Simple config, email instructions, basic pattern
`modules/cheque/`	Offline	Minimal setup example
`modules/qlopaypalcommerce/`	Online	OAuth, webhooks, refunds, API integration

Core files:

```
classes/PaymentModule.php
```
— Base payment module class
```
classes/order/Order.php
```
— Order creation
```
classes/order/OrderPayment.php
```
— Payment type constants

模块	类型	核心概念
`modules/bankwire/`	线下	简单配置、邮件说明、基础模式
`modules/cheque/`	线下	极简设置示例
`modules/qlopaypalcommerce/`	线上	OAuth、Webhook、退款、API集成

核心文件：

```
classes/PaymentModule.php
```
— 基础支付模块类
```
classes/order/Order.php
```
— 订单创建
```
classes/order/OrderPayment.php
```
— 支付类型常量

Troubleshooting

故障排除

Payment option not showing — Check: module active,
```
hookPayment
```
registered, currency enabled for module, configuration completed.
Webhook not working — Check: webhook URL registered with gateway, signature verification passing, controller accessible (no 404), module logs.
Order creation fails — Check: cart exists and not converted,
```
secure_key
```
matches, order state exists, all
```
validateOrder()
```
parameters provided.

支付选项未显示——检查：模块已激活、
```
hookPayment
```
已注册、模块启用了对应货币、配置已完成。
Webhook不工作——检查：Webhook URL已在网关注册、签名验证通过、控制器可访问（无404错误）、模块日志。
订单创建失败——检查：购物车存在且未转换、
```
secure_key
```
匹配、订单状态存在、提供了
```
validateOrder()
```
的所有参数。

Development Workflow

开发流程

Plan — Choose payment type (offline vs online), review gateway documentation, get test credentials
Setup — Create folder structure, main module file, mandatory files, install/uninstall, configuration form
Payment Flow — Create payment controller, validation/callback controller, implement
```
validateOrder()
```
, add templates
Advanced (Online) — Integrate gateway API, setup webhook handling, add transaction logging, implement refunds
Test — Test currencies, advance payment, success/failure flows, webhook notifications, refunds

规划——选择支付类型（线下/线上）、查看网关文档、获取测试凭证
设置——创建文件夹结构、主模块文件、必填文件、安装/卸载、配置表单
支付流程——创建支付控制器、验证/回调控制器、实现
```
validateOrder()
```
、添加模板
进阶（线上）——集成网关API、设置Webhook处理、添加交易记录、实现退款
测试——测试货币、预付款、成功/失败流程、Webhook通知、退款

Additional Resources

额外资源

QloApps DevDocs: https://devdocs.qloapps.com/

QloApps 开发者文档：https://devdocs.qloapps.com/