SuperAPI AI 工具集

setup-tng-ewallet

编程与开发

查看项目

更新于 11-17 02:10

技能介绍

用途

该技能用于 Touch 'n Go eWallet(TNG Digital Sdn Bhd,简称 TNGD)商户支付集成,覆盖接入、构建、调试、评审和讲解。适用于 TNGD 小程序直连、网站或应用收单、协议代扣(agreement pay)以及无代码方式(Payment Link、QR,无代码方式无需 API 工作)。

资料与阅读顺序

  • references/tng-ewallet-api.md:Mini Program Open API,包含消息结构、RSA256 签名与验签、端点目录,以及 pay、inquiryPayment、notifyPayment、refund、inquiryRefund、authorization、用户信息 API 的完整字段表、数据字典、结果码、my.tradePay、my.getAuthCode 和 SFTP 结算文件说明。在给出事实性 API 指导或编写集成代码前应先阅读。
  • references/tng-ewallet-web-acquiring.md:商户需要网页结账(无小程序)时使用,记录 TNGD WooCommerce 插件所实现的 alipayplus.acquiring.* API(该流程唯一公开来源),并列出其缺口。
  • references/account-setup.md:开通、凭据、沙箱与生产、环境变量、结算与价格链接。
  • references/source-map.md:选择正确官方页面,查看覆盖范围及仅限合作伙伴的内容。

核心工作流

  1. 确定集成面:TNGD 小程序(Open API + my.tradePay)、网站或应用结账(Web 收单 API)、协议代扣或无代码(Payment Link、QR)。
  2. 确认开通已完成。TNGD 在沙箱 UAT 通过后通过邮件下发 Client-Id、Partner ID(Merchant ID)、产品码、TNGD 公钥、API 主机和 SFTP 访问方式;没有自助 API 密钥页面。
  3. 生成 RSA 密钥对,将公钥交给 TNGD,私钥仅保存在服务端。
  4. 调用 TNGD 前,先本地创建待支付记录,使用唯一 paymentRequestId(小程序)或 merchantTransId(Web)。
  5. 服务端以签名请求调用创建 API,并用 TNGD 公钥验证响应签名。
  6. 小程序:将 actionForm.redirectionUrl 传给 my.tradePay({ paymentUrl });Web:浏览器重定向到 checkoutUrl。
  7. my.tradePay 结果码与浏览器返回 URL 仅作用户体验用途。
  8. 处理支付通知:验签、核对 ID 与金额、立即以签名的 resultStatus: "S" 应答,然后异步且幂等地处理业务。
  9. 若无最终通知,查询状态(inquiryPayment 或 order.query);不得在 U 或 PROCESSING 状态下结算。
  10. 每日对照 T+1 SFTP 结算 CSV 对账。

核心事实

  • Open API URL 模式:https://{host}/acl/api/{restful_path},例如 /v1/payments/pay;主机由 TNGD 分配,生产端点通过邮件下发。
  • 每次 Open API 调用为 POST + JSON body,请求头包含 Client-Id、Request-Time(RFC3339,毫秒精度)、Signature。
  • 签名头:Signature: algorithm=RSA256, keyVersion=<n>, signature=<value>;RSA256(SHA256withRSA)为默认,也列出 ECC224。
  • 待签字符串:POST <HTTP_URI>\n<Client-Id>.<Request-Time>.<HTTP_BODY>;响应使用 <Client-Id>.<Response-Time>.<HTTP_BODY> 与 TNGD 公钥验证。
  • 所有请求和响应(包括对 notifyPayment 的应答)都必须签名。
  • 金额格式为 {currency, value},value 为最小单位(sen)的字符串整数,例如 RM100.00 为 "10000"。
  • 收银台支付:productCode 51051000101000100001,paymentFactor.isCashierPayment: true。协议代扣:productCode 51051000101000100031,paymentFactor.isAgreementPay: true,paymentAuthCode = access token。
  • resultStatus:S 成功、F 失败、U 未知、A 已接受(按 actionForm 处理)。
  • inquiryPayment 的 paymentStatus:SUCCESS、FAIL、PROCESSING、CANCELLED;建议每 5 秒轮询,最长 1 分钟。
  • my.tradePay 结果码:9000 成功、8000 处理中、4000 失败、6001 用户取消、6002 网络错误、6004 未知。
  • 小程序调用需要 extendInfo 包含 customerBelongsTo(例如 {"customerBelongsTo":"TNG"})。
  • 幂等键:pay 为 partnerId + paymentRequestId;refund 为 partnerId + refundRequestId。
  • 结算为 T+1,入账至开通时提供的银行账户;CSV MERCHANT_SETTLEMENT_<PartnerID>_<yyyymmdd> 于 T+1 上午 9 点放在 SFTP。
  • Web 收单沙箱基础地址(插件默认):https://api-sd.tngdigital.com.my;路径为 /alipayplus/acquiring/order/create.htm、/order/query.htm、/order/refund.htm、/refund/query.htm。

关键规则

  • 商户私钥、client secret、SFTP 密码仅保存在服务端。
  • 对实际发送的字节签名:body 只序列化一次,并发送同一字符串。
  • 使用同一环境的 TNGD 公钥验证每个响应和通知签名后方可信任。
  • 不得仅凭 my.tradePay 9000、paymentReturnUrl 或 Web 的 PAY_RETURN 重定向标记已支付。
  • U 结果不是失败:不得判失败、离线退款或重建支付,应查询或等待通知。
  • notifyPayment 应答必须在收到消息时立即返回 S;业务处理异步进行。非 S 会触发重试和重复。
  • 仅当 paymentId/acquirementId、请求 ID、金额、币种 MYR 与 partner ID 均与存储的待支付记录匹配时才结算。
  • 允许部分退款,但总退款不得超过支付金额;每次退款使用新的 refundRequestId 并保留以供查询。
  • 不得自行编造生产主机、通知 URL 注册或通知头;文档未说明处应向 TNGD 确认。
  • WooCommerce 插件的通知处理未验证签名,不要沿用该缺口。

完成标准

  • 创建、查询、退款调用在服务端执行,带正确 Client-Id、Request-Time 和 RSA256 Signature。
  • 响应签名用 TNGD 公钥验证;失败拒绝并记录日志。
  • 通知端点验签、以签名的 S 应答并幂等处理。
  • 标记已支付前,按 sen 核对金额与币种。
  • 状态查询任务覆盖漏通知,且从不在 U/PROCESSING 时结算。
  • 退款流程保存 refundRequestId,用 inquiryRefund 处理 U,并阻止超额退款。
  • 测试覆盖错误签名、重复通知、金额错误、U 结果、过期订单和成功场景。
  • 配置记录 TNG_CLIENT_ID、TNG_PARTNER_ID、TNG_PRIVATE_KEY、TNG_PUBLIC_KEY、API host、notify URL 以及沙箱/生产隔离。

漏洞审查循环

当被问及 TNG eWallet 策略是否“100% 有把握”时,重复以下循环直至无事实缺口:

  1. 列出信任边界:小程序或浏览器、my.tradePay 结果、返回 URL、商户后端、TNGD Open API、通知接收端、密钥存储、数据库、退款任务、SFTP 结算。
  2. 检查绕过点:伪造通知、未签名或签名错误的 body、签名后重新序列化 body、环境密钥错误、沙箱/生产混用、金额单位错误(ringgit 与 sen)、以不同数据复用 paymentRequestId(REPEAT_REQ_INCONSISTENT)、将 U 视为失败、重复通知、处理后才应答通知、过期订单延迟支付、超额退款、退款 U 后离线退款。
  3. 补充修复:服务端签名、精确字节签名、响应与通知验签、严格 ID/金额/币种校验、持久事件日志、幂等结算、查询兜底、每日 CSV 对账。
  4. 重读 references/tng-ewallet-api.md 或 references/tng-ewallet-web-acquiring.md 的相关章节。
  5. 说明剩余不确定性:生产主机、Web 收单的通知 URL 设置、确切通知头、customerBelongsTo 取值、密钥版本、限流,以及 TNGD 仅在合作伙伴 Postman 包中提供的内容。

适用场景与限制

适用于 TNGD 支付网关的商户侧集成开发、代码评审、问题排查和技术讲解。资料未提供生产主机、通知 URL 注册方式、通知头、customerBelongsTo 全部取值、密钥版本、限流等细节,需向 TNGD 确认;Web 收单 API 的公开来源为 WooCommerce 插件实现且存在缺口。