SuperAPI AI 工具集

setup-securepay

编程与开发

查看项目

更新于 11-17 02:10

技能介绍

用途

本技能专为 SecurePay Sdn Bhd(securepay.my)支付网关的集成工作设计,适用于搭建、构建、调试、审查和解释 SecurePay 支付集成。工作需基于官方文档,主要参考文件包括 references/securepay-api.md(API v1 总体指引)、references/securepay-v2.md(API v2 细节)、references/securepay-codes.md(银行代码、状态值等)、references/account-setup.md(账户注册与配置)和 references/source-map.md(官方页面导航)。

主要能力

  • 支持 API v1:FPX 支付、Payment Session(测试版)、请求校验和生成、回调与重定向字段处理、校验和验证(含测试向量)、状态查询、列表、搜索、错误处理。
  • 支持 API v2:SecurePay Console、客户端 ID/密钥、auth_token、支付意图、DuitNow、eMandate、分账结算、封闭钱包、会员、合作伙伴 API、证书等。
  • 提供 FPX 银行代码、状态值、授权码、枚举及沙箱测试银行信息。
  • 涵盖账户注册、文档、凭证位置、沙箱与生产环境区分、接口设置、结算周期、退款政策、插件与支持。
  • 提供官方页面选择指引和文档覆盖说明。

使用方式

核心工作流如下:

  1. 选择 API 版本:默认使用 v1(生产 API),除非商户账户使用 SecurePay Console(v2 客户端 ID/密钥)。
  2. 识别环境:沙箱(v1 沙箱 https://sandbox.securepay.my/api,生产 https://securepay.my/api)。
  3. 获取该环境的接口凭证:API UID、Auth Token、Checksum Token(v1)。
  4. 在调用 SecurePay 前创建本地待处理订单,包含唯一 order_number 和预期金额。
  5. v1:构建请求校验和,然后将表单字段 POST 到 /v1/payments(通常为自动提交的浏览器表单,类似官方插件),或创建 Payment Session 并重定向到 payment_url。
  6. 将 redirect_url 视为仅用于浏览器用户体验,履约应基于服务器到服务器的 callback_url POST。
  7. 验证回调校验和:将所有收到的键按升序排序(排除 checksum),用 | 连接值,使用 Checksum Token 进行 HMAC-SHA256,恒定时间比较。
  8. 在结算前使用 Basic 认证重新查询 GET /v1/payments/status/:order_number,确认 payment_status、transaction_amount_received、currency 和 order_number。
  9. 幂等结算。对于 FPX B2B1,将 fpx_debit_auth_code 99 视为待处理,等待后续 00 回调。
  10. 当回调丢失时,使用 GET /v1/transactions/list 或 /v1/transactions/search 进行对账。

关键事实:

  • v1 创建支付:POST /v1/payments(表单编码)。v1 Payment Session(测试版):POST /apis/payments 返回 JSON payment_url。
  • v1 请求校验和字符串顺序:buyer_email|buyer_name|buyer_phone|callback_url|order_number|product_description|redirect_url|transaction_amount|uid,HMAC-SHA256 十六进制,密钥为 Checksum Token。空的可选值保留空位。
  • v1 金额为林吉特,保留两位小数(1540.40)。v2 支付意图使用以分为单位的金额(154040)。
  • v1 状态/列表/搜索/验证/会话认证:HTTP Basic uid:auth_token。支付表单 POST 携带 token(Auth Token)和 checksum 字段。
  • 验证凭证:POST /v1/merchants/validate 使用 Basic 认证和 checksum_token。
  • 公共 FPX 银行列表(无需认证):GET /public/v1/banks/b2c 和 /public/v1/banks/b2b,可选 ?status=online|offline。丢弃 VerifySign 不为 true 的响应。
  • 回调/重定向通过 POST 发送字段,如 payment_status、transaction_amount、transaction_amount_received、order_number、exchange_number、fpx_debit_auth_code、checksum。
  • v2 基础 URL:生产 https://console.securepay.my/api,暂存 https://sandbox.securepay.dev/api。认证:POST /v1/auth 使用 Basic client_id:client_secret,然后 Authorization: Bearer <auth_token>。
  • 无文档化的退款、作废或捕获 API。退款需通过支持手动处理(退款与取消政策)。
  • 结算为 T+1 工作日,截止时间 23:59 MYT;周五至周日结算在周一。
  • 速率限制和回调源 IP 未文档化。

适用场景

  • 为马来西亚商户集成 SecurePay 支付网关(FPX、DuitNow 等)。
  • 需要安全处理支付回调、校验和验证和幂等结算的开发与审查。
  • 需要参考官方文档进行调试、解释或策略审查。
  • 适用于希望确保支付集成安全性和完整性的团队。

限制

  • 无退款、作废或捕获 API 文档,退款需手动通过支持处理。
  • v1 /v1/payments 响应格式、uid 作为表单字段、v2 响应体、v2 嵌套负载校验和、PQC 请求签名、速率限制、回调 IP、重试策略、定价等未文档化。
  • v2 回调携带嵌套 payment 对象,文档未定义如何扁平化以进行校验和,建议从认证状态重查结算。
  • 生产环境支付方式可用性、定价、结算安排和 B2B1 启用需与 SecurePay 确认。
  • 官方 WooCommerce 插件不验证回调校验和,不应复制该做法。
  • 文档样本中可能包含零宽字符(U+200B),复制字符串时需注意。