用途 该技能面向 Paydibs 支付网关(Merchant Integration API v3,文档版本 4.0,日期 24 Sep 2026)的集成工作,可用于搭建、编码、调试、审查和讲解 Paydibs 支付集成。
主要能力
- 覆盖托管收银台(PAY 表单 POST)、Hosted Payment Session 卡 SDK、定期扣款 CIT/MIT、已存卡令牌、线下 DuitNow 二维码等接入面。
- 提供 PAY 请求字段、响应与回调字段、每个 Sign 公式及其校验示例、PTxnStatus 状态码、QUERY、REFUND、Hosted Payment Session、定期扣款等参考内容。
- 配套参考文档包括:paydibs-api.md(接口事实与端点目录)、account-setup.md(注册、凭据来源、环境变量名、支付方式激活、结算与定价)、paydibs-codes.md(枚举与错误码)、paydibs-recurring.md(CIT、计费规则、MIT)、paydibs-hosted-session.md(卡 SDK)、paydibs-tokens-instore.md(BINDOPT、REVOKE、DuitNow QR)、paydibs-emandate.md(E-Mandate 与直接借记)、source-map.md(文档页与场景对应)。
使用方式
- 确认环境:测试(测试账户)或生产,两套 URL 均由 Paydibs 随账户提供。
- 确认接入面:托管收银台、卡 SDK、定期 CIT/MIT、已存卡令牌或线下 DuitNow QR。
- 从 Paydibs 取得凭据:Merchant ID(6 字符)、Merchant Password(哈希密钥)和支付 URL 主机。
- 在构建 PAY 请求前,先在本地创建待处理支付记录,使用唯一 MerchantPymtID(最长 20)。
- 服务端构建 PAY 请求,计算 Sign = 文档规定字段拼接的 SHA512 十六进制值,Merchant Password 放在最前。
- 浏览器自动提交 HTML 表单(POST)到 <payment URL>/PPG/trigger;Merchant Password 严禁暴露给浏览器。
- MerchantRURL 的 POST 仅作浏览器体验,需校验 Sign,但结算应基于服务端回调或 QUERY。
- 处理 MerchantCallbackURL:解析 urlencoded 正文(内含 JSON 字符串),校验 Sign、核对字段并返回 HTTP 200。
- 仅在 Sign、MerchantID、MerchantPymtID、MerchantTxnAmt、MerchantCurrCode 与 PTxnStatus = 0 均匹配后幂等结算。
- 回调缺失或状态为 pending(2)时,用 TxnType=QUERY 请求 /PPG/trigger 兜底。
关键事实
- 端点路径:支付、查询、MIT、绑定与撤销为 /PPG/trigger;退款为 /PPG/refund;托管会话为 /PPG/create-pay-session;线下二维码为 /PPG/offline/trigger-qr;E-Mandate 为 /PPG/trigger-emandate;直接借记为 /PPG/create-ddi、/PPG/create-ddi-txn、/PPG/cancel-ddi。
- 未公开 void、capture、部分退款、结算报表或打款 API。
- 主机为“Paydibs 提供的 URL”;官方 Hosted Session SDK 硬编码 https://stgapi.paydibs.com(测试)与 https://v3api.paydibs.com(生产)。
- TxnType 取值(大写):PAY、QUERY、REFUND、REVOKE、BINDOPT、MIT。
- Sign 算法:SHA512 十六进制字符串,128 字符,纯拼接无分隔符,Merchant Password 在最前。
- PAY 签名拼接顺序:MerchantPassword + TxnType + MerchantID + MerchantPymtID + MerchantOrdID + MerchantRURL + MerchantTxnAmt + MerchantCurrCode + CustIP + PageTimeout + MerchantCallbackURL + Token(可选字段缺失时为空字符串)。
- 响应/查询签名拼接顺序:MerchantPassword + MerchantID + MerchantPymtID + PTxnID + MerchantOrdID + MerchantTxnAmt + MerchantCurrCode + PTxnStatus + AuthCode。
- 金额为令吉,必须两位小数,无千分位分隔符(1000.00,而非 1000 或 1,000.00)。
- PTxnStatus:0 成功、1 失败、2 待处理、9 已作废、10 已退款、17/18 已取消、19 已过期、20 拒付、22 银行维护、50/51 金额限制、-1 未找到、-2 内部错误。
- 回调内容类型为 application/x-www-form-urlencoded,正文是 JSON 字符串;在返回 HTTP 200 前最多重试 5 次。
- QUERY 的 PAYExists:0 存在、1 不存在、2 错误需重试;注意 0 表示已找到。
- 支付方式代码:OB 网银、CC 卡、WA 电子钱包;币种包括 MYR、SGD、PHP、VND、CNY、HKD、IDR、KHR、KRW、THB。
- 生产环境仅允许 TLS 1.2,上线前需针对生产验证 TLS 1.2。
- MerchantRURL 与 MerchantCallbackURL 查询字符串中的 & 需替换为 ;。
限制与不确定项 文档未说明的事项需向 Paydibs 确认,包括基础 URL(由 Paydibs 提供)、测试卡与测试银行、IP 白名单、速率限制、退款时间窗以及 Sign 中 null 字段的处理方式。退款响应 RefundResult 为布尔值;Paydibs 示例显示退款仅允许从次日起发起。生产环境中的支付方式可用性、费率、结算与 TLS 需在上线前与 Paydibs 核实。