SuperAPI AI 工具集

setup-ringgitpay

编程与开发

查看项目

更新于 11-17 02:10

技能介绍

RinggitPay 支付网关集成技能

用途 本技能面向 RinggitPay(RinggitPay Sdn Bhd,Ascertain Technologies 集团)支付集成工作,用于搭建、构建、调试、审查和解释 RinggitPay 支付集成。提供基于官方文档与集成测试规范的参考资料,覆盖托管支付页、WooCommerce 插件和直接借记 e-Mandate REST API 三类接入方式。

参考资料

  • references/ringgitpay-api.md:在给出事实性 API 指导或编写集成代码前阅读。包含端点目录、环境、请求与响应字段表、校验和公式、状态码、查询 API、UAT 测试数据以及直接借记(e-Mandate)REST API。
  • references/account-setup.md:当用户询问如何注册、AppId/RequestKey/ResponseKey 来源、APIURL 与 RedirectURL 设置、UAT 与生产区别、UAT 签收、支付方式、结算时间或定价时阅读。
  • references/source-map.md:查看每项事实的来源支撑及来源可信度说明——集成 PDF 虽为 RinggitPay 编写,但发现于第三方 GitHub 镜像而非 RinggitPay 域名。

核心工作流

  1. 识别环境:UAT(ringgitpay.co)或生产(ringgitpay.com)。
  2. 识别接入面:托管支付页(一次性 FPX/卡支付)、WooCommerce 插件或直接借记 e-Mandate REST API(定期)。
  3. 与 RinggitPay 确认:AppId、RequestKey、ResponseKey,以及 APIURL(服务器到服务器)和 RedirectURL(浏览器)已为该 AppId 注册。二者由 RinggitPay 配置,不随请求发送(可选 returnURL 除外)。
  4. 在跳转前创建本地待处理订单,使用唯一 orderId(最多 20 字符)和精确金额字符串(2 位小数)。
  5. 在服务端计算 checkSum = SHA256(appId|currency|amount|orderId|REQUESTKEY),并自动提交 HTML 表单 POST 到 /payment。
  6. 将 RedirectURL/ReturnURL 的 POST 视为浏览器用户体验;校验其校验和,但以 APIURL 直接消息或交易查询结果进行结算。
  7. 使用收到的原始值验证 rp_checkSum = SHA256(rp_appId|rp_currency|rp_amount|rp_statusCode|rp_orderId|rp_transactionRef|RESPONSEKEY)。
  8. 仅在 RP00、校验和、AppId、orderId、金额、币种和环境全部匹配时幂等结算。RP09 为待处理,绝不可视为最终结果。
  9. 对 pending、缺失或有争议的结果使用 POST /transactionenquiry(JSON)。

核心事实

  • 支付请求:POST https://ringgitpay.co/payment(UAT),POST https://ringgitpay.com/payment(生产)。表单 POST,name/value 对。
  • 交易查询:POST https://ringgitpay.co/transactionenquiry(UAT),POST https://ringgitpay.com/transactionenquiry(生产)。JSON 入,JSON 出。
  • 请求字段:appId、currency(MYR)、amount(2 位小数)、orderId、checkSum;可选 buyerEmail、returnURL(URL 编码,同域)、accNumber 和 accBuyerId(付款人验证)。
  • 响应字段以 rp_ 为前缀:rp_appId、rp_currency、rp_amount、rp_statusCode、rp_orderId、rp_transactionRef、rp_txnTime(UTC YYYYMMDDHH24mmSS)、rp_paymentMode(FPX、CC、DC、NA)、rp_checkSum、rp_remarks、rp_xtraInfo、rp_paymentCountry。
  • 请求和查询校验和使用 RequestKey;响应校验和使用 ResponseKey。均为 SHA-256,对管道连接值计算,密钥附加在最后。
  • 规范要求请求校验和为十六进制大写;官方插件发送小写十六进制并以大小写不敏感方式比较响应。比较时应大小写不敏感。
  • 状态 RP00 = 成功,RP09 = 待处理,IR1x/IR20 = 请求验证错误,其他 RPxx = 失败(完整表见 API 参考)。
  • RinggitPay 发送直接消息(服务器到服务器至 APIURL)和间接消息(浏览器表单 POST 至 RedirectURL,或若发送则 ReturnURL)。
  • 仅支持 MYR(官方插件 FAQ)。
  • FPX 限额:零售 B2C RM1.00 至 RM30,000.00;企业 B2B RM2.00 至 RM1,000,000.00。B2B 在企业授权人操作前保持 RP09。
  • 直接借记 API:基础 https://bills2u-api.ringgitpay.co(UAT)/ https://bills2u-api.ringgitpay.biz(生产),OAuth2 令牌来自 https://identity.ringgitpay.{co|biz}/connect/token,路径位于 /api/v1/mandate/... 下。
  • 退款、作废、捕获、付款和结算报告 API:在已找到的官方来源中均未记录(检查于 2026-10-21)。

关键规则

  • RequestKey、ResponseKey 和 DD API 客户端密钥/密码仅保留在服务端;绝不在浏览器中计算校验和。
  • 对收到的字符串值精确验证响应校验和(不要重新格式化 rp_amount);不要包含 rp_xtraInfo、rp_remarks 或 rp_paymentMode。
  • 不要仅凭 RedirectURL/ReturnURL 标记已支付;规范称浏览器重定向并非 100% 可靠。
  • 校验和不匹配意味着"忽略并记录",而非"标记订单失败"(官方插件标记失败,可能使伪造 POST 导致真实订单失败)。
  • 对照存储的订单检查 rp_amount 和 rp_currency;官方插件不检查,应补充。
  • 将 RP09 视为非最终状态,并通过交易查询重新检查;延迟更新也会到达 APIURL。
  • 保持 orderId 每次尝试唯一(RP45 = 重复卖家订单号)且在 20 字符以内。
  • APIURL 和 RedirectURL 不得包含 IP 地址或端口号(UAT 签收规则)。
  • 使用 UAT 密钥配 ringgitpay.co,生产密钥配 ringgitpay.com;绝不可混用。

完成标准 仅当满足以下条件时,RinggitPay 集成才算完成:

  • 支付表单和校验和基于存储的待处理订单在服务端生成。
  • APIURL 处理器使用 ResponseKey 验证 rp_checkSum,检查 AppId、orderId、金额、币种,并返回 HTTP 200。
  • RP00 上的结算在 APIURL、RedirectURL 和查询结果之间幂等。
  • RP09 订单通过交易查询及后续 APIURL 更新重新检查。
  • 测试覆盖错误校验和、错误金额、错误币种、未知 orderId、重复通知、RP09 后 RP00、失败代码以及带与不带 transactionRef 的查询。
  • 已捕获 UAT 签收清单项(FPX SBI Bank A/B、卡成功/失败、收据、重定向与 API 日志、查询日志、邮件)。
  • 部署文档列出 RINGGITPAY_APP_ID、RINGGITPAY_REQUEST_KEY、RINGGITPAY_RESPONSE_KEY、RINGGITPAY_ENV,以及各环境向 RinggitPay 注册的 APIURL/RedirectURL。

漏洞审查循环 当被问及 RinggitPay 策略是否"100% 有信心"时,运行此循环直到无事实缺口:

  1. 列出信任边界:结账页、自动提交表单、RinggitPay 支付页、FPX/卡通道、RedirectURL/ReturnURL 浏览器 POST、APIURL 服务器 POST、查询 API、数据库、履约任务、RinggitPay 门户设置。
  2. 检查绕过:伪造浏览器 POST、伪造 APIURL POST、重新格式化金额后的校验和、错误密钥(RequestKey vs ResponseKey)、大小写敏感的十六进制比较、UAT/生产密钥混用、错误金额或币种、重复使用 orderId、将 RP09 视为最终或失败、缺少 APIURL 注册、ReturnURL 在其他域、重复通知、查询校验和缺少空 transactionRef 槽位。
  3. 添加修复:服务端校验和、恒定时间大小写不敏感比较、严格订单匹配、持久通知日志、幂等结算、查询回退、按环境配置。
  4. 重新阅读 references/ringgitpay-api.md 中与任何缺口相关的部分。
  5. 说明剩余不确定性:未记录的重复策略、无公开 IP 允许列表、无退款 API、PDF 版本高于 v1.13(状态码"定期更新")。向 RinggitPay 索取最新规范。