用途
本技能面向需要与 PayNet 自有支付通道对接的开发者,帮助完成 PayNet 支付集成的设置、构建、调试、审查与解释。PayNet 是马来西亚的国家支付基础设施,而非商户网关。大多数商户通过银行收单机构或持牌支付网关接入 FPX 与 DuitNow,此类情况应使用对应提供方的技能。使用本技能前,应先确认调用方的角色(商户、收单机构、FPX TPA 或发卡行)与目标产品,普通商户若未获 FPX 商户或 TPA 批准,应引导至收单机构或网关。
主要能力
技能附带多个参考文件,按产品划分:
- references/paynet-api.md:入口文件,说明谁可以集成哪个产品、环境与主机、各产品的认证与签名方式、完整端点目录及详细文件链接。
- references/paynet-fpx.md:FPX 商户或 TPA 集成(B2C、B2B1、B2B2、批量退款、AE 状态查询、银行列表、校验和、证书、UAT 银行)。
- references/paynet-duitnow-pay.md:DuitNow Pay 收单 API(托管与自托管结账、保存支付方式、AutoDebit、退款、Webhook、JWT 认证)。
- references/paynet-rpp-v3.md:RPP DuitNow v3 参与方 API(JWS、信用转账 Webhook、退款意向、DuitNow Request、Reversal、AutoDebit、Consent、QR Webhook、网络管理)。
- references/paynet-duitnow-qr.md:构建或解析 DuitNow QR 字符串及收单 QR 流程。
- references/paynet-codes.md:所有状态、原因、拒绝与响应代码。
- references/account-setup.md:开发者门户注册、项目角色、认证、上线与商户注册。
- references/source-map.md:根据问题选择官方页面并查看覆盖范围。
使用方式
核心工作流如下:
- 识别调用方角色(商户、收单机构、FPX TPA、发卡行)。普通商户需收单机构或网关,除非已是获批的 FPX 商户或 TPA。
- 识别产品:FPX、DuitNow Pay、DuitNow Online Banking/Wallets v3、DuitNow Request、AutoDebit/Consent、Reversal 或 DuitNow QR。
- 识别环境:UAT(认证中心模拟器或系统验证)或生产。
- 调用 PayNet 前,先用自有唯一 ID 在本地创建待处理支付(FPX 用 fpx_sellerOrderNo/fpx_sellerExOrderNo,DuitNow Pay 用 checkoutId UUID v4,v3 用 businessMessageId)。
- 按产品要求对每个请求签名(FPX RSA-SHA1 校验和、DuitNow Pay JWT RS256、v3 JWS 含 ds 摘要),私钥仅保留在服务端。
- 按文档方式重定向付款人(FPX 全窗口表单 POST;DuitNow 银行 URL 携带 EndtoEndId、EndtoEndIdSignature、DbtrAgt)。
- 浏览器返回仅作 UX 用途,结算依据已验证的服务端到服务端消息(FPX 直连 AC 回复 OK、DuitNow Pay Update Payment Status Webhook、v3 Webhook)。
- 服务端消息缺失时按文档查询(FPX AE、DuitNow Pay GET /v2/bw/checkout-status、v3 POST /v3/transactions/enquire),遵守速率限制。
- 仅在文档规定的最终状态(FPX fpx_debitAuthCode 00;DuitNow Pay substate CLEARED)进行幂等结算。
适用场景
适用于 FPX 直连商户或 TPA 集成、DuitNow Pay 收单 API 对接、RPP DuitNow v3 参与方 API 开发、DuitNow QR 字符串构建与解析,以及相关状态码、账户设置与官方文档映射的查询。也适用于对已有 PayNet 集成进行调试、审查或解释。
限制
- PayNet 开发者门户需注册并经 PayNet 验证(ask@paynet.my)后方可上线。
- DuitNow Pay 商户需隶属收单机构网络,收单机构须为已启用 Online Banking/Wallets、Consent 与 AutoDebit 的 RPP 参与方。
- FPX 生产端点 URL 未在公开文档中提供;DuitNow Pay API 基础主机未公开,样例 redirectUrl 主机为 https://duitnow-pay.uat.inet.paynet.my:8443。
- 所有 PayNet API 要求 TLS 1.2;限流调用返回 429 Quota has been exceeded;PayNet 强烈不建议沙盒负载测试。
- 许多 v3 规范标注为“beta”或“specification review”,构建前需与 commercial@paynet.my 确认可用性。
- 部分细节(主机、IP、凭证、证书、产品批准)依赖 PayNet 入驻流程,或属未公开的生产细节,存在不确定性。