SuperAPI AI 工具集

setup-kiple

编程与开发

查看项目

更新于 11-17 02:10

技能介绍

用途 该技能面向 Kiple(kiplePay,原 Webcash)支付网关的集成工作,可用于搭建、构建、调试、审查和讲解 Kiple 支付集成。

信息来源说明 Kiple 没有公开 API 文档,技能中的事实来自 Kiple 自己的官方插件(GitHub 组织 m2c,「Kiplepay Sdn Bhd」)以及真实的网关响应。回答时应向用户说明这一点,并提示用户就标注为「未文档化」的内容向 Kiple 确认。技能包含三份参考文件:references/kiple-api.md(环境、端点目录、托管表单字段、金额规则、返回与回调字段、返回码、SHA-1 哈希公式及示例、查询 API、定期与拆分订单字段、旧版 iOS SDK);references/account-setup.md(注册、所需凭据、插件设置、UAT 与正式环境、支付方式开通、结算、退款、价格);references/source-map.md(定位某条事实对应的官方插件文件,以及未覆盖内容)。

核心工作流

  1. 确定环境:UAT(uat.kiplepay.com)或生产(kiplepay.com)。
  2. 确定接入面:托管表单(一次性)、银行卡定期扣款、拆分订单或平台插件。
  3. 确认凭据:对应环境的 Merchant ID 与 Secret Key,店铺币种为 MYR。
  4. 在构建表单前,先用唯一的 ord_mercref 和精确金额字符串(两位小数)在本地创建待支付记录。
  5. 服务端构建表单:必填字段加 version=2.0、ord_returnURL、dynamic_callback_url,以及 merchant_hashvalue = sha1(secret + ord_mercID + ord_mercref + amountDigits)。
  6. 以 POST 自动提交表单到 /wcgatewayinit.php。
  7. 在服务端回调(带 nbcb)和浏览器返回时,用已存储的值重新计算 ord_key = sha1(secret + merchantId + ord_mercref + amountDigits + returncode),并以恒定时间比较。
  8. 标记已支付前,调用查询 URL,要求响应体为 S。
  9. 在 returncode=100、引用、金额、商户 ID 匹配且 wcID 未出现过时,幂等结算。
  10. 浏览器返回仅作用户体验;若回调未到达,改用查询接口。

主要事实

  • 支付入口:UAT https://uat.kiplepay.com/wcgatewayinit.php,正式 https://kiplepay.com/wcgatewayinit.php(PHP SDK 使用同主机的 /gateway)。
  • 查询:GET /enquiry.php 或 /enquiries,参数 ord_mercID、ord_mercref、ord_totalamt;纯文本响应 S、F、A、Invalid Parameters、Records not Found。
  • 哈希算法:对无分隔符的明文拼接做 SHA-1,输出小写十六进制,secret 在最前。
  • amountDigits 为提交的 ord_totalamt 去掉 . 和 ,(50.00 变为 5000);拆分订单还需去掉 |。
  • 最低金额 RM1.00;返回 URL 必须为完整地址(网关校验页)。
  • returncode:100 成功,E1 失败,E2 中止/超时,-1 无效商户请求。
  • 响应含 wcID(Kiple 交易 ID)、ord_key、ord_mercref、ord_totalamt、payment_type、entry_id、error_description。
  • 服务端回调发往 dynamic_callback_url,携带 nbcb。
  • ord_date 格式 Y-m-d H:i:s;version 为 2.0。
  • 币种仅 MYR(所有官方插件)。
  • 定期扣款:仅银行卡(payment_code=CC),ord_recurring_enable=1,支持月/季/年,需要 Kiple 定期订阅;取消在 Kiple 门户操作。
  • 拆分订单:ord_mercID 与 ord_totalamt 以管道符分隔,ord_mmercID 为主商户,使用主商户 secret 计算哈希。
  • 任何官方来源中都没有退款、作废、捕获或打款 API。

关键规则 Secret Key 保留在服务端,绝不放入客户端 JS 或表单;不得仅凭浏览器返回发货,需校验 ord_key 并重新查询;响应哈希须用本地存储的商户 ID、引用和金额重算,而非提交值;金额固定两位小数、无千分位,且哈希与提交字符串一致;每次尝试使用新的 ord_mercref 并映射回订单(插件会追加 uniqid);按 wcID 去重,返回与回调可能同时到达;UAT 主机配 UAT secret,正式主机配正式 secret;E1/E2 回调时官方 WooCommerce 插件将订单置为挂起而非失败,最终取消前需重新查询;WooCommerce「Verify Key」帮助文本写「随便填」,应忽略,该值必须是 Secret Key;若返回处理需要买家会话,将会话 Cookie 设为 SameSite=None; Secure;不要臆造退款、Webhook 重试或支付方式代码行为,标注为未文档化并向 Kiple 确认。

完成标准 表单由服务端构建,含 version=2.0、两位小数金额、唯一 ord_mercref 和正确 merchant_hashvalue;ord_returnURL 与 dynamic_callback_url 为对应环境的绝对 HTTPS 地址;两个处理器都用恒定时间比较校验 ord_key;结算要求 returncode=100、哈希有效、查询结果为 S,且金额、引用、商户 ID 匹配;按 wcID 与本地支付状态幂等处理;测试覆盖错误哈希、错误金额、错误引用、E1、E2、-1、重复回调、回调缺失时查询兜底及成功;部署文档列出 KIPLE_MERCHANT_ID、KIPLE_SECRET_KEY、KIPLE_ENV、返回与回调 URL,以及 UAT/正式隔离。

漏洞审查循环 当被问及 Kiple 策略是否「100% 有把握」时,循环执行:列出信任边界(浏览器表单、Kiple 托管页、返回处理器、回调处理器、查询调用、数据库、履约任务、定期回调、Kiple 门户);检查绕过点(伪造返回 POST、对提交值计算哈希、金额格式不一致 50 与 50.00、复用 ord_mercref、生产环境用 UAT secret、旧 webcash.com.my 主机不匹配、重复 wcID、未签名的定期回调、DNS 或 HTTP 层面的查询欺骗、拆分订单使用子商户 secret);补充修复(存储值哈希校验、恒定时间比较、通过 HTTPS 在发货前查询、唯一引用、wcID 唯一索引、环境绑定配置、持久回调日志);重读相关参考章节;说明剩余不确定性(回调确认格式、重试策略、定期回调签名、退款、支付方式代码及 Kiple 私有 API 文档内容),需向 Kiple 确认。

适用场景与限制 适用于使用 Kiple 的商户或开发者进行支付表单搭建、回调校验、定期扣款与拆分订单集成及安全审查。限制:官方无公开 API 文档,部分行为未文档化;无退款/作废/捕获/打款 API;币种仅 MYR;价格、结算周期等账户信息需查阅 references/account-setup.md 或向 Kiple 确认。