Tulus(亦名 SnapNPay)是由 Tulus Digital Sdn Bhd 运营的支付网关,同一套 API、字段名和签名机制在两个品牌下通用。本技能用于 Tulus 支付网关的集成工作,包括设置、构建、调试、审查和解释。
用途与适用场景
本技能服务于需要接入 Tulus 支付网关的开发者,覆盖从初始配置到生产部署的完整流程。典型场景包括:创建一个 FPX 或银行卡支付结账流程;在服务器端生成签名并构造自动提交表单;验证来自支付网关的直接回调并完成订单结算;通过报告 API 对账遗漏或待处理的支付;以及审查现有集成是否存在签名、幂等或环境配置方面的漏洞。
参考资料结构
技能附带多份参考文档,应在提供 API 指导或编写集成代码前阅读。references/tulus-api.md 包含端点目录、主机地址、认证方式、结账字段、签名算法及验证过的测试向量、回调字段、报告 API、二维码生成器以及已知的文档不一致之处。references/tulus-codes.md 包含完整的 fpx_debit_auth_code 表、状态映射、zakat 机构代码、zakat 类型和州枚举以及表单模式字段。references/tulus-partner-apis.md 仅在用户作为合作伙伴向 Tulus 推送交易(如 ADB、Grab webhook)或自定义收据和收据邮件时使用。references/account-setup.md 涵盖入驻流程、AuthToken 和 API 密钥的存放位置、预发与生产环境、环境变量名称和结算说明。references/source-map.md 用于定位合适的官方页面。
核心工作流程
确认机构代码(入驻时分配)以及商户是否已从商户仪表板获得 API 密钥(UUID)。API 密钥用于签名订单和验证回调。与 Tulus 确认环境和结账主机地址。在重定向前,以 refNo 为键在本地创建待处理支付记录。在服务器端构造订单字段:agency、refNo、amount、email、returnUrl(可选 cancelUrl),添加 exp = 当前时间 + 60 秒,进行签名,并渲染一个自动提交的 POST 表单到 /v2/checkout。在 returnUrl 上同时处理两种 POST:直接回调(带签名,服务器到服务器,具有权威性)和间接浏览器返回(无签名,仅用于展示)。验证直接回调签名时,对所有 POST 字段(除 signature 外)排序,使用 Go url.QueryEscape 编码,不包含路径和 exp。仅在验证 status=success 并匹配 refNo、agency 和净额后结算,并快速返回 HTTP 200。使用签名的报告 API(/api/report/v1/fpxrequest 或 /api/report/v1/payment)对账待处理或遗漏的支付。
关键技术事实
文档记载的结账端点为 POST https://tulus.my/v2/checkout,内容类型为 application/x-www-form-urlencoded。但该 URL 在 2026-10-21 返回 404,而 https://pay.tulus.my/v2/checkout 有响应;SDK 演练场向 https://pay.tulus.my/(生产)和 https://paydev.tulus.my/(预发,FPX 测试银行)提交。需与 Tulus 确认主机地址。报告主机为 https://reports.tulus.my,同时也是商户仪表板。认证使用 AuthToken JWT(Authorization: Bearer)用于报告,从仪表板复制;或使用按机构分配的 API 密钥 UUID 仅作为 HMAC 密钥。旧版 token 或用户名密码方式已弃用。签名算法:HMAC-SHA256(message, key) 十六进制,取前 16 个字符。密钥为去除连字符的 UUID,十六进制解码为 16 个原始字节。出站消息格式为 <path>?<按 RFC 3986 排序的查询字符串,包含 exp>,适用于 GET 报告和 POST 结账/二维码。结账路径为 /v2/checkout。回调消息为所有 POST 字段(除 signature 外)的 ksorted k=v&... 形式,使用 Go url.QueryEscape 编码(空格为 +),不包含路径和 exp。amount 为保留两位小数的林吉特字符串,最低 1.00(FPX B2B 为 2.00)。refNo 不得包含 ~;~ 用于附加 extraData。直接回调状态为 success、pending、failed,约每 30 秒重试直到收到 HTTP 2xx。直接回调金额为净额,addCharge 为平台费;间接返回金额为总额。生产环境中未签名或签名错误的结账请求返回 HTTP 403 拒绝。实测支付建议使用以 12.34 结尾的金额。退款、取消/作废、循环和令牌化 API 在官方文档中未记载(截至 2026-10-21 核查)。
安全与实现规则
API 密钥和 AuthToken 仅限服务器端保存,密钥绝不上线传输。绝不应依据间接浏览器返回或 cancelUrl 进行履约。不要对 ASCII UUID 直接做 HMAC,不要使用完整的 64 字符摘要,验证回调时不要添加 exp 或路径。不要向结账表单添加未签名字段(例如 CSRF token),每个提交字段都会被检查。为 returnUrl 免除 CSRF 保护;响应 200 且不重定向。签名比对应使用恒定时间比较。结算需幂等:同一成功通知可能多次到达(重试和仪表板重发),已记录的成功不可回退。将签名的净额与存储的金额进行交叉核对。读取 fpx.payment_method 以区分 FPX、卡(mpgs)和其他方式;字段名对所有方式均保持 fpx* 前缀。不要将可下载的 WooCommerce 插件作为验证参考,其签名检查被禁用且未添加 exp。
完成标准
一个 Tulus 集成仅在满足以下条件时视为完成:签名器通过 tulus-api.md 中的两个官方测试向量;结账在重定向时于服务器端签名(60 秒 exp),且仅提交已签名字段;returnUrl 为公开 HTTPS,免除 CSRF,并分别处理直接和间接 POST;直接回调经过验证,匹配 refNo、agency、净额,并在成功时仅结算一次;pending 保持 pending;定时任务通过签名的报告 API 对账;测试覆盖签名错误(403)、重放成功(不重复履约)、金额篡改、未签名间接 POST、pending 转为 success 等情形;部署文档列出 TULUS_AGENCY、TULUS_API_KEY、TULUS_CHECKOUT_URL、TULUS_REPORT_URL、TULUS_RETURN_URL 以及预发与生产环境的值。
漏洞审查循环
当被问及 Tulus 策略是否“100% 有信心”时,运行以下循环直至无事实缺口:列出信任边界(结账表单、买家浏览器、Tulus 结账主机、银行/FPX、直接回调、间接返回、cancelUrl、数据库、履约任务、报告 API、商户仪表板)。检查绕过路径(伪造间接 POST、无签名回调、对 ASCII 密钥签名、~ 或空格编码错误、过期 exp、未签名额外表单字段、金额总额与净额混淆、错误 agency、重复成功、成功后的延迟 pending、错误结账主机、预发密钥用于生产)。添加修复措施(重定向时服务器端签名、恒定时间验证、严格匹配 refNo/agency/金额、行锁加幂等履约、终态守卫、签名的报告 API 回退、独立环境配置)。重新阅读 references/tulus-api.md 中与任何缺口相关的章节。说明剩余不确定性:结账主机、预发凭据、机构启用的支付方式和费用、结算时间以及任何未记载的退款流程。