payment-integration

支付集成

使用 SePay（越南支付）和 Polar（全球 SaaS 变现）实现支付处理。

适用场景

适用于以下实现：

• 支付网关集成（结账、处理）
• 订阅管理（试用、升级、账单）
• Webhook 处理（支付通知）
• 二维码支付（VietQR、NAPAS）
• 按用量计费（计量、额度）
• 自动发放权益（许可证、GitHub 访问权限、Discord 身份组）
• 客户门户（自助管理）
• 银行转账自动化（越南银行）
• 含定价信息的产品目录

平台选择

选择 SePay 的场景：

• 越南市场（VND 货币）
• 银行转账自动化
• VietQR/NAPAS 支付
• 本地支付方式
• 直接监控银行账户

选择 Polar 的场景：

• 全球 SaaS 产品
• 订阅管理
• 按用量计费
• 自动发放权益（GitHub、Discord、许可证）
• Merchant of Record（税务合规）
• 数字产品销售

快速参考

SePay 集成

• 概览与身份验证：references/sepay/overview.md - 平台功能、API/OAuth2 身份验证、支持的银行
• API 参考：references/sepay/api.md - 端点、交易、银行账户、虚拟账户
• Webhook：references/sepay/webhooks.md - 设置、负载结构、验证、重试逻辑
• SDK 用法：references/sepay/sdk.md - Node.js、PHP、Laravel 实现
• 二维码：references/sepay/qr-codes.md - VietQR 生成、模板、集成
• 最佳实践：references/sepay/best-practices.md - 安全性、模式、监控

Polar 集成

• 概览与身份验证：references/polar/overview.md - 平台功能、身份验证方式、MoR 概念
• 产品与定价：references/polar/products.md - 产品类型、定价模式、按用量计费
• 结账：references/polar/checkouts.md - 结账流程、嵌入式结账、链接
• 订阅：references/polar/subscriptions.md - 生命周期、升级、降级、试用
• Webhook：references/polar/webhooks.md - 事件类型、签名验证、监控
• 权益：references/polar/benefits.md - 自动发放（GitHub、Discord、许可证、文件）
• SDK 用法：references/polar/sdk.md - TypeScript、Python、PHP、Go、框架适配器
• 最佳实践：references/polar/best-practices.md - 安全性、模式、监控

集成脚本

• SePay Webhook 验证：scripts/sepay-webhook-verify.js - 验证 SePay webhook 的真实性
• Polar Webhook 验证：scripts/polar-webhook-verify.js - 验证 Polar webhook 签名
• 结账辅助工具：scripts/checkout-helper.js - 为两个平台生成结账会话

实施工作流

SePay 实施

1. 加载 references/sepay/overview.md 以设置身份验证
2. 加载 references/sepay/api.md 或 references/sepay/sdk.md 以进行集成
3. 加载 references/sepay/webhooks.md 以处理支付通知
4. 使用 scripts/sepay-webhook-verify.js 验证 webhook
5. 加载 references/sepay/best-practices.md，为生产环境做好准备

Polar 实施

1. 加载 references/polar/overview.md，了解身份验证和概念
2. 加载 references/polar/products.md 以设置产品
3. 加载 references/polar/checkouts.md 以了解支付流程
4. 加载 references/polar/webhooks.md 以处理事件
5. 使用 scripts/polar-webhook-verify.js 验证 webhook
6. 如需自动发放权益，加载 references/polar/benefits.md
7. 加载 references/polar/best-practices.md，为生产环境做好准备

核心功能

SePay：

• 支付网关（二维码、银行转账、银行卡）
• 通过 Webhook 监控银行账户
• 基于订单的虚拟账户
• VietQR 生成 API
• 支持 44 家以上越南银行
• 速率限制：每秒 2 次调用

Polar：

• 记录商户（全球税务合规）
• 订阅生命周期管理
• 基于用量的计费（事件、计量器）
• 自动化权益（GitHub、Discord、许可证）
• 客户门户（自助服务）
• 多语言 SDK
• 速率限制：每分钟 300 个请求

说明

实现支付集成时：

1. 根据需求识别平台（越南本地还是全球、支付类型）
2. 按需逐步加载相关参考资料
3. 使用平台专属方法实现身份验证
4. 根据业务模式设置产品和定价
5. 实现结账流程（托管式、嵌入式或由 API 驱动）
6. 配置 Webhook 并进行适当验证
7. 处理支付事件（成功、失败、退款）
8. 在投入生产前于沙盒环境中充分测试
9. 使用平台分析工具进行监控和优化

仅加载当前实现步骤所需的参考资料，以高效利用上下文。