SuperAPI AI 工具集

setup-kineticpay

编程与开发

查看项目

更新于 11-17 02:10

技能介绍

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。

核心工作流

  1. 识别环境:生产或沙箱(沙箱是 Collection 页面上的开关,端点相同)。
  2. 识别集成面:自定义服务器集成、WooCommerce、GiveWP、Gravity Forms、Forminator、WHMCS 或无代码收款表单/链接。
  3. 确认仪表盘设置:已批准的公司、具有名称和网站 URL 的 Collection、其商家密钥,以及(使用 API v2 时)API 密钥。
  4. 在调用 KineticPay 之前,创建本地待处理支付记录并生成唯一 invoice 字符串。
  5. 让买家选择 FPX 银行,并将其代码作为 bank 发送。
  6. 服务端 POST https://manage.kineticpay.my/payment/create,携带 merchant_key、invoice、amount、description、bank、callback_success、callback_error、callback_status。
  7. 将返回的 html(自动提交表单)输出到浏览器,把买家送往银行。出错时显示错误消息。
  8. 任何回调命中时,不要信任请求体。服务端重新查询 GET /payment/status?merchant_key=...&invoice=...。
  9. 仅当重新查询返回 code "00" 且 invoice、amount 与本地状态匹配时,才进行幂等结算。
  10. 为回调未到达的待处理支付保留重新查询任务。

核心事实

  • 支付基础地址(所有官方插件使用):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% 确信"时,运行此循环直到没有事实缺口:

  1. 列出信任边界:浏览器、自动提交表单、FPX 银行页面、回调路由、后端账单创建器、KineticPay /payment/*、API v2、数据库、履约任务、重新查询任务、仪表盘 Collection 设置。
  2. 检查绕过:伪造回调 POST 含 transaction_status_code: "00"、重放回调、猜测 invoice、跨尝试重用 invoice、创建前篡改金额、生产环境遗留沙箱、商家密钥在日志或前端泄露、陈旧的待处理从未重新查询、激进轮询耗尽速率限制、站点使用错误的 Collection 密钥。
  3. 添加修复:服务端重新查询作为唯一真相来源、唯一不可猜测的 invoice、对照本地记录检查金额、幂等结算、脱敏日志、429 退避、部署时检查沙箱。
  4. 重新阅读 references/kineticpay-api.md 中与任何缺口相关的章节。
  5. 说明剩余不确定性:未文档化的状态响应字段、未文档化的回调负载、无退款或循环 API、卡计划访问权限,以及 callback_status 是否由服务器到服务器调用。告知用户与 KineticPay 支持(support@kineticpay.my)确认这些事项。

限制

  • 官方文档对部分 API v2 端点(Bills、Collections、Collection Forms、Transactions、Settlements、Points)未发布页面,相关功能暂未提供详细说明。
  • 状态响应模式未文档化,需记录完整响应确认金额字段。
  • 回调负载未文档化,且无回调签名机制。
  • 无退款或循环 API 的公开文档。
  • 卡、电子钱包和 BNPL 未在已发布 API 字段中暴露。