用途
该技能面向 Billplz 支付网关的集成开发，适用于支付收款、支付表单、目录（Catalog）以及 Payment Order 打款（payout）相关工作。可用于搭建、构建、调试、审查和解释 Billplz 支付集成。
主要能力
- 依据内置参考文档提供事实性 API 指导与集成代码编写。
- 覆盖 Collection/Bill 结账、Payment Form/Catalog、Payment Order 打款、OAuth 合作方流程、插件以及 zakat 流程等产品类型。
- 处理沙箱（billplz-sandbox.com）与生产（billplz.com）两套环境。
- 涉及 X Signature、V5 checksum、卡令牌化、状态页、GitHub 插件说明以及结算/安全注意事项。
- 提供账户注册、所需 API 密钥、凭据来源与仪表盘设置方面的说明（见 references/account-setup.md）。
使用方式（核心工作流）
- 识别产品：Collection/Bill 结账、Payment Form/Catalog、Payment Order 打款、OAuth 合作方流程、插件或 zakat 流程。
- 识别环境：沙箱 billplz-sandbox.com 或生产 billplz.com。
- 确认凭据：API Secret Key、Collection ID、X Signature Key。
- 在创建 Billplz 账单前，先在本地创建待处理（pending）支付记录。
- 在服务端于某个 Collection 下创建 Bill，金额以分为单位，并设置 callback_url 与可选的 redirect_url。
- 将付款人重定向到返回的 Bill URL。
- 在回调/重定向时使用 HMAC-SHA256 与 X Signature Key 校验 X Signature。
- 在 Bill ID、Collection ID、金额、paid/state 与本地引用匹配后，幂等地完成结算。
核心事实
- 生产 API 基础地址：https://www.billplz.com/api/。
- 沙箱 API 基础地址：https://www.billplz-sandbox.com/api/。
- 认证：HTTPS Basic Auth，API Secret Key 作为用户名，密码留空。
- API 接受 application/x-www-form-urlencoded 与 JSON；响应为 JSON。
- 货币仅支持 MYR。金额使用最小货币单位，例如 100 等于 RM 1.00。
- 每个 Bill 都属于一个 Collection。Open Collection 无法通过 API 创建账单。
- callback_url 是可靠后端更新的必需项；redirect_url 可选，用于用户体验。
- 回调与重定向的执行顺序不固定；处理程序必须防止重复更新。
- X Signature 使用 HMAC-SHA256，对排序后的键值源字符串配合 X Signature Key 计算。
- V5 接口（如 Payment Order）使用 epoch 与 HMAC-SHA512 校验和。
关键规则
- API Secret Key 与 X Signature Key 仅保留在服务端。
- 使用 X Signature 回调/重定向。出于安全原因，较新账户默认禁用 Basic 回调/重定向。
- 不要仅依赖重定向 URL；浏览器重定向不保证发生。
- 对有效回调快速返回 HTTP 200。Billplz 会重试失败的回调，回调失败可能导致账户等级下降。
- 在标记为已支付前，校验金额、paid/state、Bill ID、Collection ID 与本地引用。
- 当需要准确的当前选项时，从 Billplz 拉取 FPX 银行或支付网关可用性；静态列表可能过时。
- 对于 Payment Order 打款，校验 HMAC-SHA512 校验和，并使用唯一的 reference_id 防止重复创建打款。
- 不要抓取状态页用于业务逻辑；状态页仅用于运维感知。
完成标准
Billplz 结账集成仅在满足以下条件时才算完成：
- 账单创建在服务端、来自已认证的用户流程。
- callback_url 已配置、通过 HTTPS 公开，并能接收 POST 支付完成事件。
- 在回调与重定向处理程序中进行任何结算前，已校验 X Signature。
- 结算检查提供方、Bill ID、Collection ID、金额、paid/state 与本地引用。
- 重复的回调/重定向重放无害。
- 伪造重定向、错误金额、错误 Bill ID 与无效签名均无法解锁访问。
- 沙箱支付已完成并记录。
- 测试覆盖无效签名、重复通知、错误金额/Collection 以及成功结算。
- 部署文档包含 API Secret Key、X Signature Key、Collection ID、回调 URL、重定向 URL 以及沙箱/生产分离。
漏洞审查循环
当被问及某个 Billplz 策略是否“100% 确信”时，运行以下循环直到没有事实性缺口：
- 列出信任边界：浏览器重定向、后端账单创建、Billplz API、回调接收器、数据库、履约任务、仪表盘设置与打款任务。
- 检查绕过：伪造重定向、伪造回调、错误的 X Signature 源字符串、错误金额、错误账单/Collection、重复回调、回调先于重定向、重定向先于回调、未支付/到期账单被标记为已支付、已删除账单、API Secret Key 泄露、沙箱/生产混用、Payment Order 重复打款、错误的 V5 校验和顺序。
- 添加修复：服务端账单创建、先建本地待处理支付、X Signature HMAC 校验、严格的金额/状态检查、幂等键、持久事件日志、公开 HTTPS 回调、环境分离、Payment Order reference_id 与审计轨迹。
- 重新阅读 references/billplz-docs.md 中与任何缺口相关的章节。
- 若剩余不确定性取决于账户套餐、已启用的支付网关、当前定价、运维状态页、仅合作方可用的 OAuth 或仅仪表盘可设的配置，则明确说明。
适用场景
- 在应用中集成 Billplz 收款结账。
- 构建或调试 Billplz 支付表单与目录。
- 实现 Payment Order 打款流程。
- 审查现有 Billplz 集成的安全性与幂等性。
- 解释 Billplz API 流程、签名机制与环境配置。
限制
- 货币仅支持 MYR。
- Open Collection 无法通过 API 创建账单。
- 部分能力（如 OAuth 合作方流程）可能仅限合作方；账户套餐、已启用支付网关、当前定价与仪表盘设置相关事项需以实际账户为准。
- 状态页不应用于业务逻辑。
- 关于具体收费、价格、平台支持范围等，资料未提供。