用途
setup-moby 是一个面向 MOBY(MobyPay、Moby Omni)支付网关集成的辅助技能,用于在搭建、构建、调试、审查和解释 MOBY 支付集成时提供参考依据。它围绕 MOBY 官方文档、MOBY OpenAPI 规范和 MOBY 插件整理集成流程与关键规则,帮助开发者按环境、接口面和凭证完成服务端集成。
主要能力
- 覆盖托管结账(hosted checkout)与 Direct API 两种主要接入方式。
- 支持令牌与周期扣款(card tokens、token charges、订阅 API、Dashboard Recurring Billing)。
- 支持 POS/kiosk 的 TCP 集成、IPP 分期计划及 Visa 计划取消。
- 提供账户开通、凭证来源、沙箱与生产环境、Dashboard 功能、环境变量、结算与定价注意事项的参考。
- 提供 source-map 以定位主题对应的官方页面并查看覆盖范围。
- 明确回调签名算法(HMAC-SHA256,8 个字段固定顺序)、状态查询、退款、撤销、捕获等接口调用要点。
- 列出沙箱测试数据、速率限制、错误处理以及 MOBY 各来源之间的已知冲突。
使用方式
- 读取 references/moby-api.md,获取环境、认证、端点目录、托管结账与 Direct API 字段表、回调载荷、签名算法、状态/详情查询、捕获/撤销/退款、沙箱数据、速率限制、错误、插件及来源冲突。
- 需要周期扣款时读取 references/moby-recurring.md;需要 POS/kiosk 时读取 references/moby-pos.md;需要账户与凭证信息时读取 references/account-setup.md;需要定位官方页面时读取 references/source-map.md。
- 确认环境:沙箱 https://dev.pay.mobycheckout.com 或生产 https://pay.mobycheckout.com。
- 确认接入面:托管结账(默认)、单一方法的 Direct API、令牌/周期扣款、Dashboard 支付链接或周期计费、插件、POS/kiosk。
- 确认凭证:对应环境的 Client ID 与 Secret Key(由 merchantsupport@moby.my 签发);保险类商户需提供 NRIC。
- 在调用 MOBY 前,先在本地创建待处理支付记录,包含唯一 referenceNo、预期金额(MYR,两位小数)和环境。
- 通过 POST /api/auth/token 获取 Bearer 令牌,缓存至 expired_at,遇到 401 时刷新。
- 服务端创建会话:托管结账调用 /api/merchant/payment/checkout/hosted 返回 payLink;Direct API 调用 /api/merchant/payment/direct/pay 返回 payUrl,然后跳转客户。
- returnUrl 重定向仅作为用户体验处理,即使带有签名查询串也不作为支付成功依据。
- 收到 callbackUrl 的 POST 后,首先校验签名(HMAC-SHA256,使用 Secret Key,对 8 个字段按固定顺序拼接)。
- 仅当 status 为 success 且 referenceNo、金额、环境、商户匹配时进行幂等结算,并返回 HTTP 200 {"status":"success"}。
- 回调缺失、延迟或非成功时,通过 /api/merchant/payment/detail 或 /status 重新查询。
适用场景
- 需要按 MOBY 官方规范完成支付网关服务端集成的开发任务。
- 需要审查现有 MOBY 集成是否正确处理回调签名、幂等结算、金额与引用号校验。
- 需要调试令牌获取、会话创建、状态查询、退款/撤销/捕获、周期扣款或 POS/kiosk 相关流程。
- 需要在上线前对照完成标准与信任边界进行漏洞审查。
限制与注意事项
- Secret Key 必须保持在服务端;它用于签发令牌并作为回调 HMAC 密钥。
- 不得依据 returnUrl、payLink/payUrl 创建、前端消息或未签名载荷标记支付成功。
- 签名必须对收到的值原样计算,不得重新格式化金额或时间;null 映射为空字符串(注意 JavaScript String(null) 为 "null")。
- 使用常量时间比较,签名不匹配时拒绝;记录原始载荷而非放宽校验。
- 不要在 callbackUrl/returnUrl 中添加自有查询参数,除非在哈希前剥离;同时处理 MOBY 可能追加的以 ? 开头的键。
- referenceNo 每次尝试必须唯一;托管结账不返回会话 ID,referenceNo 是唯一关联键。
- 回调处理必须幂等;同一 referenceNo 可能对应多笔交易和重复回调。
- 金额比较使用两位小数字符串或整数分,不要使用浮点数。
- 不要在沙箱随意测试电子钱包,可能产生真实扣款。
- 不要基于 /v2/...、Financing、Loyalty 或 Merchant Management 端点构建,它们尚未在生产环境提供。
- 文档、OpenAPI 与插件存在不一致时(见参考文件列表),上线前应与 MOBY Merchant Support 确认。
- 直连支付的回调送达、部分退款字段、回调重试策略、保险 NRIC 字段名、令牌扣款 client_id 位置与 custom_data 类型、x-token 签发、结算时间、账户方法激活和定价等事项在资料中未完全明确,需向 MOBY 确认。
- 未记录 webhook IP 列表、签名头、Dashboard webhook 注册表或公开状态页。
完成标准(摘要)
令牌、会话创建和状态查询均在服务端运行,并使用环境匹配的 Client ID、Secret Key 与 base URL;跳转前存在唯一 referenceNo 的本地待处理支付记录;回调处理以常量时间校验 8 字段 HMAC;结算检查 status、referenceNo、金额、环境和商户并保持幂等;仅在持久化处理后返回 HTTP 200;缺失或非最终回调通过 detail/status 对账;退款与撤销在签名回调或状态确认前记为待处理;测试覆盖有效签名、篡改字段、null merchantOrderRef、错误金额、重复回调、失败/待处理/取消及 ? 前缀查询键;部署文档列出 MOBY_CLIENT_ID、MOBY_SECRET_KEY、base URL、callback URL、return URL 及沙箱/生产分离。