SuperAPI AI 工具集

setup-paydibs

编程与开发

查看项目

更新于 11-17 02:10

技能介绍

用途 该技能面向 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(文档页与场景对应)。

使用方式

  1. 确认环境:测试(测试账户)或生产,两套 URL 均由 Paydibs 随账户提供。
  2. 确认接入面:托管收银台、卡 SDK、定期 CIT/MIT、已存卡令牌或线下 DuitNow QR。
  3. 从 Paydibs 取得凭据:Merchant ID(6 字符)、Merchant Password(哈希密钥)和支付 URL 主机。
  4. 在构建 PAY 请求前,先在本地创建待处理支付记录,使用唯一 MerchantPymtID(最长 20)。
  5. 服务端构建 PAY 请求,计算 Sign = 文档规定字段拼接的 SHA512 十六进制值,Merchant Password 放在最前。
  6. 浏览器自动提交 HTML 表单(POST)到 <payment URL>/PPG/trigger;Merchant Password 严禁暴露给浏览器。
  7. MerchantRURL 的 POST 仅作浏览器体验,需校验 Sign,但结算应基于服务端回调或 QUERY。
  8. 处理 MerchantCallbackURL:解析 urlencoded 正文(内含 JSON 字符串),校验 Sign、核对字段并返回 HTTP 200。
  9. 仅在 Sign、MerchantID、MerchantPymtID、MerchantTxnAmt、MerchantCurrCode 与 PTxnStatus = 0 均匹配后幂等结算。
  10. 回调缺失或状态为 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 核实。