用途
本技能面向 M1Pay(MobilityOne Sdn Bhd)支付网关的集成工作,覆盖配置、构建、调试、审查和解释等任务。开始前应先阅读 references/m1pay-api.md,其中包含端点目录、环境、OAuth2 令牌调用、创建交易字段、查询交易字段、回调字段、精确的签名与验签字符串、状态值、渠道、FPX 银行列表、FPX 错误码及文档中记录的缺口;涉及注册、所需凭证、Client ID、Client Secret 与密钥文件位置、沙箱(UAT)设置、商户门户设置、环境变量名、支付渠道、定价或结算时间时,阅读 references/account-setup.md;选择适用的官方页面或核对文档覆盖范围时,阅读 references/source-map.md。
主要能力与核心流程
- 识别环境:UAT(沙箱,m1payall.com 主机)或生产(m1pay.com.my 主机)。
- 确认商户门户设置:服务器 IP 白名单、Web Redirect URL、Host-to-Host Callback URL、Client ID、Client Secret、私钥文件、M1Pay 公钥证书。
- 调用 M1Pay 前,先在本地创建带唯一 merchantOrderNo 的待支付记录。
- 服务端从 Keycloak 令牌端点获取 access_token(grant_type=client_credentials)。
- 构建签名串,用商户私钥以 SHA1withRSA 签名,十六进制编码为 signedData。
- POST 创建交易(form-urlencoded,Authorization: Bearer <token>),保存返回的 transactionId,将客户重定向至返回的 M1Pay 地址。
- 浏览器回到 Web Redirect URL 仅视为用户体验,需服务端调用 Get Transaction 读取真实状态。
- 收到 Host-to-Host 回调时,先用 M1Pay 公钥证书按文档回调串验签,再信任内容。
- 仅当 merchantOrderNo、金额、币种与所用渠道的成功状态全部匹配时才幂等结算。
- 回调缺失或重定向结果不明时,用 Get Transaction 重新查询。
关键事实
- 令牌:沙箱为 POST https://keycloak.m1pay.com.my/auth/realms/master/protocol/openid-connect/token,生产为 .../realms/m1pay-users/...。
- 创建交易:沙箱 POST https://gateway.m1payall.com/m1paywall/api/transaction,生产 https://gateway.m1pay.com.my/wall/api/transaction。
- 查询交易:GET .../m1paywall/api/m-1-pay-transactions/{transactionId}(沙箱)或 .../wall/api/m-1-pay-transactions/{transactionId}(生产)。
- FPX 银行列表:GET .../bank-list/B2C 与 .../bank-list/B2B1(公开,无需认证)。
- 请求与回调体均为 x-www-form-urlencoded;币种固定为 MYR。
- 金额以林吉特计(1000 或 1000.00,无逗号);签名串需两位小数(10.00)。
- 请求签名串:productDescription|transactionAmount|exchangeOrderNo|merchantOrderNo|transactionCurrency|emailAddress|merchantId。
- 回调验签串:transactionAmount|fpxTxnId|sellerOrderNo|status|merchantOrderNo。
- 两种场景算法均为 SHA1withRSA(RSA PKCS#1 v1.5 加 SHA-1),签名为十六进制字符串。
- 成功状态因渠道而异:FPX 为 APPROVED,CARD_PAYMENT 为 CAPTURED,EMONEI/ALIPAY/UMOBILE 为 SUCCESSFUL,BOOST 为 COMPLETED。
- 省略 channel 与 fpxBank 将显示 M1Pay Payment Wall;传空值会报错。
- 回调最多重试 15 次,间隔 10 分钟。
- UAT 仅支持 ONLINE_BANKING 与 CARD_PAYMENT;测试 FPX 银行为 SBI Bank A。
- 商户服务器 IP 须在 M1Pay 注册(IP 过滤)。
关键规则
- Client Secret、私钥文件与令牌仅保留在服务端。
- 不得仅凭 Web Redirect URL 标记已支付;须重新查询 Get Transaction。
- 解析为业务状态前,先用 M1Pay 证书验证回调 signedData。
- 按实际所用渠道的成功值比较,通用“success”检查是错误的。
- 签名串中 transactionAmount 必须恰好两位小数,且请求体发送相同值。
- 令牌、密钥、证书与主机只能来自同一环境,禁止混用 UAT 与生产。
- 回调与重查询处理须幂等;重试最多可达 15 次。
- 不得臆造退款、取消、循环、打款或结算 API;M1Pay 未公开文档化这些接口。
- 对未记录细节(回调确认响应体、重定向参数、令牌有效期、额外电子钱包渠道码)应标注并向 M1Pay 支持确认。
完成标准
- 令牌、创建交易与查询交易调用均在白名单 IP 的服务端运行。
- signedData 按精确文档串以 SHA1withRSA 生成,金额两位小数。
- 跳转前将返回的 transactionId 与本地 merchantOrderNo 关联保存。
- 重定向处理器只触发服务端 Get Transaction 重查询。
- 回调处理器用 M1Pay 公钥证书验签并拒绝失败。
- 结算校验 merchantOrderNo、金额、MYR、渠道与该渠道成功状态。
- 重复回调、重试与重查询不会造成重复履约。
- 测试覆盖签名错误、金额错误、订单号错误、失败/过期状态、重复回调及各渠道成功。
- 部署文档列出 M1PAY_ENV、M1PAY_MERCHANT_ID、M1PAY_CLIENT_ID、M1PAY_CLIENT_SECRET、M1PAY_PRIVATE_KEY_PATH、M1PAY_PUBLIC_CERT_PATH、重定向 URL、回调 URL 与服务器 IP。
漏洞审查循环
被问及 M1Pay 策略是否“100% 有把握”时,反复执行以下循环直至无事实缺口:列出信任边界(浏览器重定向、商户结账、后端令牌客户端、Keycloak、M1Pay 墙 API、回调接收器、表单解析器、数据库、履约任务、商户门户设置、密钥文件);检查绕过路径(伪造重定向成功、伪造回调、签名字段顺序错误、金额缺两位小数、十六进制大小写不匹配、证书错误、UAT/生产混用、令牌过期、渠道成功值错误、复用 merchantOrderNo、重复回调、回调未发送、IP 未白名单、私钥轮换);补充修复(服务端重查询、严格验签、本地字段常量时间比较、按渠道成功映射、唯一订单号、持久事件日志、幂等结算、独立环境配置、密钥轮换手册);重读 references/m1pay-api.md 中与缺口相关的章节;对文档沉默之处(退款、回调确认、重定向参数、令牌过期、额外渠道码、非 FPX 回调的 fpxTxnId、空 exchangeOrderNo 处理)明确说明剩余不确定性。
适用场景与限制
适用于 M1Pay 支付集成的开发、调试与安全审查,尤其是 FPX、卡支付及电子钱包渠道的创建交易、回调验签与幂等结算。限制在于:官方文档未公开退款、取消、循环、打款与结算接口,相关内容不得编造;回调确认响应体、重定向参数、令牌有效期、额外渠道码等细节暂未提供,需向 M1Pay 支持确认;UAT 仅支持 ONLINE_BANKING 与 CARD_PAYMENT。