SuperAPI AI 工具集

setup-boldpay

编程与开发

查看项目

更新于 11-17 02:09

技能介绍

用途

setup-boldpay 用于 BOLD.Pay(MACROKIOSK)支付集成相关的工作,包括搭建、构建、调试、审查和解释集成实现。由于 BOLD.Pay 没有公开的 API 参考,该技能以官方 MACROKIOSK WordPress.org WooCommerce 插件源码(v1.7.1)为基础,整理出端点目录、请求与响应字段、AccessToken 算法、查询、状态与错误码,以及尚未文档化的内容。

主要能力

  • 参考 boldpay-api.md:提供 API 事实依据和集成代码编写依据。
  • 参考 account-setup.md:覆盖注册、用户名与 API Key 位置、域名/IP 限制、WooCommerce 插件设置、沙箱访问、渠道、价格与结算等问题。
  • 参考 source-map.md:说明某一事实对应的源文件及覆盖范围与缺口。

使用方式

核心工作流:

  1. 识别环境:沙箱(uat.pay.etracker.cc)或生产(pay.etracker.cc)。
  2. 识别接入面:WooCommerce 插件、OpenCart/EasyStore 插件,或仿照插件协议的自定义集成。
  3. 确认门户设置:已批准的 BOLD.Pass 用户名、API Key,以及在 Domain/IP Restrictions 中配置的域名和服务器 IP。
  4. 先在本地创建待处理支付记录,包含预期金额(保留 2 位小数,单位令吉)、新的唯一 PayID、将要发送的 CustIP,以及使用的回调和通知 URL。
  5. 在服务端计算 AccessToken:UPPER(MD5(UPPER(Username + "4" + Amount + CustIP + PayID + CallbackURL + NotificationURL + ApiKey)))。
  6. 将浏览器重定向到 PaymentRequest?,携带全部字段(URL 和文本需 URL 编码)。
  7. 在浏览器返回或收到通知时,用存储值重新计算令牌并做恒定时间比较。
  8. 服务端调用 QueryRequest,从重定向 Location 的查询字符串读取结果。
  9. 校验查询返回的 TransactionID、OrderNumber、PayID 是否匹配,然后在 query Status = SUCCESS 时幂等结算。
  10. 对通知 POST 回复 OK。

关键事实

  • 生产支付页:https://pay.etracker.cc/BoldPayApi/PaymentRequest;沙箱支付页:https://uat.pay.etracker.cc/BoldPayApi/PaymentRequest。
  • 状态查询:https://pay.etracker.cc/BoldPayApi/QueryRequest(沙箱主机为 uat.pay.etracker.cc;插件在该环境使用 http,HTTPS 也可响应)。
  • 创建支付是带查询字符串的浏览器 GET 重定向,不是 JSON API。
  • 请求字段:AccessToken、Username、CustIP、PymtMethod(4)、Amount、Description、CustName、CustEmail、CustPhone、OrderNumber、PayID、CallbackURL、NotificationURL、ApiKey、Origin、CurrencyCode。
  • CurrencyCode:1 为 MYR,3 为 THB。
  • Amount 为令吉且必须恰好 2 位小数,不是分。
  • AccessToken 为大写十六进制 MD5,哈希内 URL 为原始形式(不编码)。
  • 响应字段:AccessToken、TransactionID、OrderNumber、PayID、Status、Reason、PymtMethod、IssuingBank。
  • 状态值:SUCCESS、PENDING、FAIL、REFUNDED、REVERSED;被拒绝的请求返回数字错误码。
  • 渠道代码:CC、DD(网银)、WA(电子钱包)、BNPL、OTC。
  • QueryRequest 参数:AccessToken、APIKey、Username、PayID、CallBackUrl(注意大小写)。
  • 通知为服务端 POST,回复正文 OK。
  • API Key 位于 BOLD.Pass > Admin Management > Business Setting > API Key。
  • 未公开退款、订阅、分期字段或打款 API。

关键规则

  • 响应 AccessToken 是请求令牌的回显,不对 Status 签名,且曾出现在浏览器 URL 中。不能仅凭回调字段结算,必须通过 QueryRequest 结算。
  • 令牌必须用存储的预期值(金额、CustIP、URL)重算,不能用回调中的值。
  • QueryRequest 保持 TLS 校验开启(插件关闭了校验,不要照搬)。
  • API Key 按设计会出现在支付 URL 中,应通过 Domain/IP Restrictions 限制并在泄露时轮换。
  • 每次尝试生成新的 PayID,复用会返回 416。
  • CustPhone 仅发送数字。
  • 每笔支付使用一个稳定的 CustIP 并存储;请求与回调之间变化会导致令牌失效。
  • 结算需幂等:浏览器返回和通知会针对同一笔支付同时到达。
  • 已支付订单不能因迟到的 PENDING 或 FAIL 而回退。
  • 不要引用费用、限额或结算时间,这些取决于商户协议。

适用场景

适用于在 WooCommerce、OpenCart/EasyStore 或自定义系统中对接 BOLD.Pay,编写或审查支付创建、回调、通知、查询与结算逻辑,以及排查令牌不匹配、PayID 复用、状态处理等问题。

限制

无公开 API 指南;自定义集成的 Origin 取值、PymtMethod 含义、通知重试策略、沙箱凭据、限额、退款流程等尚未明确,需与 MACROKIOSK 确认。费用、限额与结算时间按商户协议,技能不作说明。