SuperAPI AI 工具集

setup-cardbizpay

编程与开发

查看项目

更新于 11-17 02:09

技能介绍

用途 该技能面向 CardBizPay 支付网关的集成开发,用于搭建、实现、调试、审查和解释 CardBizPay 支付集成。资料给出的参考文档入口包括:references/cardbizpay-api.md(环境、端点目录、签名算法、Merchant API、状态码与文档缺陷)、references/cardbizpay-opa.md(卡令牌、商户发起扣款、预授权与捕获、/opa/* 接口)、references/account-setup.md(注册、凭据、回调 URL、沙箱、支付方式、结算与定价)以及 references/source-map.md(事实对应的官方页面)。

主要能力

  1. 环境区分:测试环境 https://uat.cardbizpay.com/paymentgateway 与生产环境 https://www.cardbizpay.com/paymentgateway。
  2. API 族区分:Merchant API(/Payment/,托管支付页)与 Open Payment API(/opa/,卡令牌)。
  3. 接入确认:管理员创建的商户档案、Merchant No、Access Key 与签名用 Secret Key、API 访问开启、Payment Return URL(Merchant API)或 Notify URL(Open Payment API)登记、已订阅支付方式。
  4. 下单与签名:本地创建唯一 OrderId(/Payment/Pymt 最多 25 字符)的待支付订单,服务端按文档字段顺序拼接值,计算 Signature = base64(HMAC-SHA512(secret, 拼接值)),由浏览器自动提交 HTML 表单 POST 到 [Base URL]/Payment/Pymt。
  5. 返回处理:在 Payment Return URL 接收表单 POST,按响应字段顺序对收到的字符串验签,检查 RespCode="00"、StatusCode="A"、MerchantNo、OrderId、TrxnAmount,并保存 TrxnId 供撤销与退款使用。
  6. 查询补偿:返回缺失、无法验签或非终态(N、W)时用 GET /Payment/PymtEnq 重新查询。
  7. 幂等结算:同一订单只转为已支付一次,无论收到多少次回发或查询结果。

关键事实 请求均为 HTML 表单 POST,查询为 GET;字段名为区分大小写的 PascalCase。签名使用商户 Secret Key 的 HMAC-SHA512,输出 base64;待签串仅含值、无分隔符、按文档字段顺序,跳过 Signature 及值为空的可选字段。官方测试向量可复现:1000000000000001M12345678910.50 配合密钥 Ws123456Ws987654,得到给定的 base64 签名。可选字段仍须以参数提交,未使用时传空值。金额为马来西亚林吉特字符串,最多两位小数,无千分位分隔符;文档未定义货币字段。ReqDate 格式为 yyyyMMddHHmmss,Open Payment API 拒绝与主机时间相差超过 60 分钟的 ReqDate。PymtMethodSelect 可取空(全部)、Card、FPX、FPX B2C、FPX B2B、e-Wallet、DuitNow,多个值用逗号分隔;订阅 e-Wallet 时实践中需要 CustMobile,且应提供 CustEmail 以避免被拒。响应码 00 表示批准/接受;支付状态包括 A 批准、D 拒绝、N 待处理(未支付 3 天后取消)、W 等待状态、V 已撤销、C 已取消、Q 部分退款、R 全额退款,Open Payment API 另有 P 预授权与 T 预授权取消。撤销仅限当日且全额返还;退款可全额或多次部分,每次需唯一 RefundId(最多 20 字符)。支付页会话计数为 15 分钟。Payment Return URL 不是请求字段,由 CardBizPay 在商户档案上配置(有门户登录时可在 Merchant Portal 修改)。

使用方式要点 Secret Key 仅保留在服务端,签名只在服务端计算,不在浏览器 JavaScript 中完成;不得仅凭浏览器落地页或未验签/验签失败的 POST 标记为已支付;对收到的原始字符串值验签,不要在哈希前重新格式化金额;签名与提交的字符串一致(发送 "10.5" 就签 "10.5",后续撤销、退款、查询使用同一字符串);以恒定时间比较签名;各环境使用独立的 Merchant No 与 Secret Key,不得混用测试凭据与生产地址;OrderId 每笔交易唯一(重复为状态 22,已支付为 13);N 与 W 视为非终态,应重新查询而非提前判失败;返回 URL 处理需幂等;文档歧义处先在生产前的测试环境向 CardBizPay 确认。测试应覆盖错误签名、金额错误、订单错误、重复回发、拒绝(D)、待处理(N/W)、批准(A)以及官方签名测试向量;部署文档需列出 CARDBIZPAY_MERCHANT_NO、CARDBIZPAY_SECRET_KEY、CARDBIZPAY_BASE_URL 及各环境登记的返回 URL。

完成标准与限制 资料给出了一套集成完成标准,包括服务端构建与签名、各环境登记回调地址、按响应字段顺序验签、结算校验多项字段并保存 TrxnId、查询覆盖缺失或非终态结果、撤销与退款使用已存 TrxnId 与原始金额字符串等。至于返回回发是浏览器还是服务器到服务器、查询响应格式、Transaction List 编码、档案级 API 开启、已订阅支付方式与定价等,公开文档未明确,资料亦提示这些尚不确定;具体收费与价格暂未提供。