用途
该技能用于 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:选择正确官方页面,查看覆盖范围及仅限合作伙伴的内容。
核心工作流
- 确定集成面:TNGD 小程序(Open API + my.tradePay)、网站或应用结账(Web 收单 API)、协议代扣或无代码(Payment Link、QR)。
- 确认开通已完成。TNGD 在沙箱 UAT 通过后通过邮件下发 Client-Id、Partner ID(Merchant ID)、产品码、TNGD 公钥、API 主机和 SFTP 访问方式;没有自助 API 密钥页面。
- 生成 RSA 密钥对,将公钥交给 TNGD,私钥仅保存在服务端。
- 调用 TNGD 前,先本地创建待支付记录,使用唯一 paymentRequestId(小程序)或 merchantTransId(Web)。
- 服务端以签名请求调用创建 API,并用 TNGD 公钥验证响应签名。
- 小程序:将 actionForm.redirectionUrl 传给 my.tradePay({ paymentUrl });Web:浏览器重定向到 checkoutUrl。
- my.tradePay 结果码与浏览器返回 URL 仅作用户体验用途。
- 处理支付通知:验签、核对 ID 与金额、立即以签名的 resultStatus: "S" 应答,然后异步且幂等地处理业务。
- 若无最终通知,查询状态(inquiryPayment 或 order.query);不得在 U 或 PROCESSING 状态下结算。
- 每日对照 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% 有把握”时,重复以下循环直至无事实缺口:
- 列出信任边界:小程序或浏览器、my.tradePay 结果、返回 URL、商户后端、TNGD Open API、通知接收端、密钥存储、数据库、退款任务、SFTP 结算。
- 检查绕过点:伪造通知、未签名或签名错误的 body、签名后重新序列化 body、环境密钥错误、沙箱/生产混用、金额单位错误(ringgit 与 sen)、以不同数据复用 paymentRequestId(REPEAT_REQ_INCONSISTENT)、将 U 视为失败、重复通知、处理后才应答通知、过期订单延迟支付、超额退款、退款 U 后离线退款。
- 补充修复:服务端签名、精确字节签名、响应与通知验签、严格 ID/金额/币种校验、持久事件日志、幂等结算、查询兜底、每日 CSV 对账。
- 重读
references/tng-ewallet-api.md或references/tng-ewallet-web-acquiring.md的相关章节。 - 说明剩余不确定性:生产主机、Web 收单的通知 URL 设置、确切通知头、customerBelongsTo 取值、密钥版本、限流,以及 TNGD 仅在合作伙伴 Postman 包中提供的内容。
适用场景与限制
适用于 TNGD 支付网关的商户侧集成开发、代码评审、问题排查和技术讲解。资料未提供生产主机、通知 URL 注册方式、通知头、customerBelongsTo 全部取值、密钥版本、限流等细节,需向 TNGD 确认;Web 收单 API 的公开来源为 WooCommerce 插件实现且存在缺口。