SuperAPI AI 工具集

setup-oxpay

编程与开发

查看项目

更新于 11-17 03:10

技能介绍

用途

本技能用于 OxPay(OxPay Financial / OxPay Malaysia)支付网关的集成工作,覆盖安装配置、集成开发、问题调试、代码审查和方案解释。在给出 API 事实性说明或编写集成代码前,应先阅读 references/oxpay-api.md;涉及商户开通、密钥位置、商户门户、MID/TID、上线测试、支付方式开通、结算报表、定价或支持渠道时,阅读 references/account-setup.md;需要定位官方页面或核对文档覆盖范围时,阅读 references/source-map.md。

主要能力

  • 支持两种接入方式:Hosted Payment Page(POST /payment-page,终端需开通 Ecommerce 功能)与商户自建收银台的 Create Payment(POST /payment,卡数据需商户自身满足 PCI DSS)。
  • 支持创建支付、QR(MPQR)支付、支付查询、退款(POST /refund)、VOID/取消(POST /void)及付款(Payouts)。
  • 提供 Webhook 接收与签名校验说明,以及退款、VOID 通过对应 Webhook 确认最终结果的流程。
  • 说明签名算法:对紧凑形式 JSON 请求体(token 间无空白、保持原始键序)做 HMAC-SHA256,输出小写十六进制,使用 Sign Key 签名。

使用方式

  1. 确认商户已完成入驻,并取得 MID(merchant_id,最长 9 字符)与 TID(terminal_id,恰好 14 字符)。
  2. 选择接入面:托管收银页或自建 Create Payment。
  3. 先在本地创建待支付订单,merchant_reference_id 在每个终端内唯一(1 至 100 字符)。
  4. 将请求 JSON 序列化为紧凑形式,用 Sign Key 做 HMAC-SHA256 签名,发送同一字节内容,并携带 Authorization: Bearer <API_KEY>、Signature: <hex> 和 User-Agent 请求头。
  5. 托管收银将浏览器重定向到 body.oxpay_hpp_url;QR(MPQR)在 payment_expiry_time 之前渲染 body.qr_string。
  6. 在 notification_url 接收支付 Webhook,先用 Sign Key 校验 Signature 头再解析。
  7. 仅当 headers.status_code 为 0、body.transaction_state 为 success(预授权捕获场景为 captured),且 merchant_reference_id、oxpay_txn_id、金额与币种均与本地订单一致时,才做幂等结算。
  8. Webhook 延迟或缺失时,用 GET /payment/{oxpay_txn_id} 或 GET /payment?merchant_reference_id=... 重新查询。
  9. 退款用 POST /refund(针对成功的 sale),作废/取消用 POST /void,最终结果以退款或 VOID Webhook 为准。

关键事实

  • 生产基础 URL:https://api.oxpayfinancial.com。OpenAPI 规格中列出的沙箱为 https://api.uat.oxpayfinancial.com,但 Getting Started 称“无 UAT 环境”,测试在生产环境用 OxPay 测试用例完成,需与 OxPay 确认。
  • 规格中 API 版本为 2.0.2,可选请求头 OxPay-Version: 2.0.1。
  • 鉴权头:Authorization: Bearer <API_KEY>(密钥形如 ak-...)。
  • 完整性头:Signature 为用 Sign Key 对紧凑 JSON 体计算的 HMAC-SHA256 小写十六进制值,POST 请求必须携带,OxPay 在每个 Webhook 中也会发送。
  • 每个请求都必须携带 User-Agent。
  • GET 查询类端点与 GET /payouts/{unique_reference} 在规格中只需 Authorization 与 User-Agent,不需要 Signature。
  • 金额为正整数,以最小货币单位表示(文档示例:SGD 1 = 100),MYR 即 sen。
  • 币种为 ISO 4217 三位字母代码;公开示例仅用 SGD,MYR 支持取决于账户。
  • headers.status_code:0 成功、1 待处理、2 拒绝、3 错误;拒绝/错误返回 HTTP 400。
  • transaction_state 枚举:success、requested、authorized、pending、rejected、error、expired、voided、refunded、captured、capture_submitted、capture_rejected。
  • 文档中的品牌:card、alipay、wechat pay、grabpay、shopeepay、atome、dash、PayNow、upi。FPX、DuitNow、Touch 'n Go 未出现在公开 API 文档中(核查于 2026-10-21)。
  • 卡支付 capture 为 false 表示预授权;文档未提供捕获端点。
  • 商户门户:https://merchant.oxpayfinancial.com,登录 https://login.oxpayfinancial.com/login;API 密钥在 Configurations > API Keys > Add New Key 添加。
  • 支持邮箱 support@oxpayfinancial.com,支持站点 https://oxpay.freshdesk.com/support/home。

适用场景

适用于需要在服务端实现 OxPay 收银页跳转、创建支付、QR 支付、Webhook 结算、订单查询、退款与 VOID 的集成项目,以及对这些流程进行代码审查、排障和文档解释的工作。也可用于梳理集成中的信任边界与常见绕过风险(如伪造成功跳转、伪造 Webhook、签名与重序列化不一致、Pending 误判为已支付、重复 Webhook、退款重放、预授权误当已捕获等)。

限制与注意事项

  • API Key 与 Sign Key 只能保存在服务端。
  • 必须对实际发送的字节签名,签名后不得美化打印或让 HTTP 客户端重新序列化请求体。
  • 信任 Webhook 任何字段前必须先校验 Signature,并使用常量时间比较。
  • 不得仅凭 success_url、前端回调、status_code 为 1 或创建支付响应就标记已支付(MPQR 会返回 Pending)。
  • 结算前须校验金额、币种、merchant_reference_id、oxpay_txn_id、MID/TID 与状态。
  • Webhook 处理必须幂等,以 oxpay_txn_id 加交易类型为键。
  • 除非商户满足 PCI DSS,不得向 /payment 发送原始卡数据,应改用托管收银页。
  • merchant_reference_id 须在每个终端内唯一,并在重试间保持稳定。
  • /payment-page 的会话 ID 会过期,过期后需重新申请。
  • Webhook 重试策略、源 IP、要求的 HTTP 响应及限流数值均无文档,不得声称。
  • 承诺 MYR、FPX、DuitNow、电子钱包及 BNPL 可用性前,须先与 OxPay 确认。

完成标准

托管收银页或创建支付在服务端以 Bearer API Key、Signature 与 User-Agent 头运行;签名字符串与发送请求体字节一致并用已知向量测试;Webhook 处理程序在解析前用 Sign Key 校验 Signature 并快速响应;结算检查 status_code、transaction_state、参考号、金额、币种与终端;重复、延迟 Webhook 与重新查询均幂等;退款与 VOID 流程保存 oxpay_original_txn_id 并从其 Webhook 结算;测试覆盖错误签名、错误金额/币种/参考号、待处理、拒绝、过期、重复与成功;部署文档列出 OXPAY_API_KEY、OXPAY_SIGN_KEY、OXPAY_MERCHANT_ID、OXPAY_TERMINAL_ID、OXPAY_BASE_URL、通知 URL 与上线测试结果。