KineticPay Payment Gateway 集成技能
用途 本技能用于 KineticPay(kineticpay.my)支付网关的集成工作,包括搭建、构建、调试、审查和讲解。适用于自定义服务器集成、WooCommerce、GiveWP、Gravity Forms、Forminator、WHMCS,以及无代码收款表单/链接等场景。
资料来源 在给出 API 事实性指导或编写集成代码前,先阅读 references/kineticpay-api.md,其中包含端点目录、账单创建字段、回调与重新查询流程、状态码、FPX 银行代码、速率限制、错误以及官方文档的缺口。 用户询问注册、商家密钥/API 密钥位置、沙箱模式、环境变量、支付方式可用性、结算或定价时,阅读 references/account-setup.md。 需要确定某项事实对应的官方页面或插件文件,或了解公开文档未覆盖的内容时,阅读 references/source-map.md。
核心工作流
- 识别环境:生产或沙箱(沙箱是 Collection 页面上的开关,端点相同)。
- 识别集成面:自定义服务器集成、WooCommerce、GiveWP、Gravity Forms、Forminator、WHMCS 或无代码收款表单/链接。
- 确认仪表盘设置:已批准的公司、具有名称和网站 URL 的 Collection、其商家密钥,以及(使用 API v2 时)API 密钥。
- 在调用 KineticPay 之前,创建本地待处理支付记录并生成唯一 invoice 字符串。
- 让买家选择 FPX 银行,并将其代码作为 bank 发送。
- 服务端 POST https://manage.kineticpay.my/payment/create,携带 merchant_key、invoice、amount、description、bank、callback_success、callback_error、callback_status。
- 将返回的 html(自动提交表单)输出到浏览器,把买家送往银行。出错时显示错误消息。
- 任何回调命中时,不要信任请求体。服务端重新查询 GET /payment/status?merchant_key=...&invoice=...。
- 仅当重新查询返回 code "00" 且 invoice、amount 与本地状态匹配时,才进行幂等结算。
- 为回调未到达的待处理支付保留重新查询任务。
核心事实
- 支付基础地址(所有官方插件使用):https://manage.kineticpay.my。
- 创建账单:POST /payment/create。重新查询:GET /payment/status。
- 账单认证是 Collection 的 merchant_key,在创建时放在请求体、状态查询时放在查询字符串中。无头部认证,无签名。
- API v2 基础地址:https://manage.kineticpay.my/api/v2,认证 Authorization: Bearer <API_KEY>,头部 Accept 与 Content-Type: application/json。
- API v2 已文档化端点:GET /ping、GET /bank、GET /company。Bills、Collections、Collection Forms、Transactions、Settlements 和 Points 在文档导航中列出,但没有已发布页面(截至 2026-10-21 检查)。
- 支付成功码为 "00"(重新查询时的 code,WooCommerce 回调 POST 中的 record.transaction_status_code)。
- amount 以令吉为单位,保留两位小数(例如 "12.50"),不是 sen。仅支持 MYR。
- FPX 银行代码如 MB2U0227、BCBB0235、PBB0233;从 GET /api/v2/bank 获取实时列表。
- 速率限制:每用户每分钟 60 次请求;响应头 X-RateLimit-Limit、X-RateLimit-Remaining;超限返回 HTTP 429。
- 校验错误返回 JSON {"error": {"field": ["message"]}}(在 /payment/status 上观察到 HTTP 200)。
- v2 列表端点分页:page、perPage(默认 20,最大 40),元数据在 meta.pagination。
- 商家密钥:Collection 页面,输入 Collection 名称和网站 URL 后生成。API 密钥:https://manage.kineticpay.my/api-key。
关键规则
- 商家密钥和 API 密钥仅限服务端保存。切勿放入浏览器代码。
- KineticPay 未文档化回调签名或校验和。切勿仅凭回调体、重定向或查询字符串标记已支付;始终服务端重新查询 /payment/status。
- 重新查询会将 merchant_key 放在 URL 查询字符串中。不要记录完整的重新查询 URL;在 HTTP 客户端日志中脱敏。
- 每次支付尝试的 invoice 必须唯一,并在重定向前存储。官方插件使用站点前缀加订单 ID 加后缀(例如 MYSHO123KNWC)。
- 将重新查询的 code、invoice、amount 与本地记录比对。状态响应模式未文档化;记录完整响应并确认其返回哪个金额字段。
- 幂等结算:同一 invoice 可能命中 callback_success、callback_status 和重新查询任务。
- 发送 amount 为两位小数的令吉字符串。不要发送 sen 整数。
- 将 WooCommerce 插件的 3 秒 cron 及 API 参考中列出的插件缺陷视为应避免的模式,而非复制。
- 上线前在 Collection 上禁用沙箱模式,并用小额在生产环境测试一次。
- 卡、电子钱包和 BNPL 未在任何已发布 API 字段中暴露;公开账单流程为带银行代码的 FPX。
完成标准 仅当以下条件满足时,KineticPay 集成才算完成:
- 账单创建在服务端运行,merchant_key 来自环境变量,且仅在本地待处理记录存在后才渲染 html 响应。
- 结账收集有效的 FPX 银行代码(来自 GET /api/v2/bank 或经过验证的列表)。
- 三个回调 URL 均指向服务端路由,该路由重新查询 /payment/status 且从不信任请求体。
- 结算在幂等事务中检查 code === "00"、invoice、amount、MYR 和本地状态。
- 重新查询任务在速率限制(60/分钟)内对账待处理支付。
- 测试覆盖:伪造回调体含 "00"、未知 invoice、金额不匹配、重复回调、失败 code、创建时错误响应、429 处理。
- 部署文档列出 KINETICPAY_MERCHANT_KEY、KINETICPAY_API_KEY(如使用 v2)、回调基础 URL 和沙箱开关状态。
漏洞审查循环 当被问及 KineticPay 策略是否"100% 确信"时,运行此循环直到没有事实缺口:
- 列出信任边界:浏览器、自动提交表单、FPX 银行页面、回调路由、后端账单创建器、KineticPay /payment/*、API v2、数据库、履约任务、重新查询任务、仪表盘 Collection 设置。
- 检查绕过:伪造回调 POST 含 transaction_status_code: "00"、重放回调、猜测 invoice、跨尝试重用 invoice、创建前篡改金额、生产环境遗留沙箱、商家密钥在日志或前端泄露、陈旧的待处理从未重新查询、激进轮询耗尽速率限制、站点使用错误的 Collection 密钥。
- 添加修复:服务端重新查询作为唯一真相来源、唯一不可猜测的 invoice、对照本地记录检查金额、幂等结算、脱敏日志、429 退避、部署时检查沙箱。
- 重新阅读 references/kineticpay-api.md 中与任何缺口相关的章节。
- 说明剩余不确定性:未文档化的状态响应字段、未文档化的回调负载、无退款或循环 API、卡计划访问权限,以及 callback_status 是否由服务器到服务器调用。告知用户与 KineticPay 支持(support@kineticpay.my)确认这些事项。
限制
- 官方文档对部分 API v2 端点(Bills、Collections、Collection Forms、Transactions、Settlements、Points)未发布页面,相关功能暂未提供详细说明。
- 状态响应模式未文档化,需记录完整响应确认金额字段。
- 回调负载未文档化,且无回调签名机制。
- 无退款或循环 API 的公开文档。
- 卡、电子钱包和 BNPL 未在已发布 API 字段中暴露。