CommercePay(Commerce DotAsia Payments,payments.commerce.asia)支付网关集成技能,用于配置、构建、调试、审查与解释 CommercePay 支付集成。使用前应阅读 references/commercepay-api.md 获取 API 事实;需要渠道与银行代码时读 references/commercepay-codes.md;账户注册、凭证、后台位置、环境变量、结算与价格等读 references/account-setup.md;按主题找官方页面用 references/source-map.md。
用途与范围:覆盖直接集成(商户自行渲染渠道)、托管会话收银台(CommercePay 页面)、循环扣款、保存支付、预授权、退款与出款。
主要能力:环境区分(staging 与 production);四个凭证(Merchant Id、Username、Password、Secret Key);POST /api/TokenAuth/Authenticate 获取 accessToken(有效期 86400 秒);除鉴权外所有请求需 Content-Type: application/json、Authorization: Bearer、Abp-TenantId 与 cap-signature;cap-signature 算法为 lowercase(完整 URL + 递归按键排序、压缩、去 null 的 camelCase JSON) 后以 Secret Key 做 HMAC-SHA256 十六进制;RequestPayment、InitialSession、Query、RefundPayment、QueryRefund 等端点;金额为最小单位整数(1000 = MYR 10.00);timestamp 为 Unix 毫秒;响应为 ABP 信封结构。
使用方式:先识别环境与接口形态,确认该环境四个凭证;服务端获取并缓存令牌;先用唯一 referenceCode 与预期金额创建本地待支付记录;对其余请求签名;服务端携带 callbackUrl 调用 RequestPayment 或 InitialSession 并保存 transactionNumber 或 sessionNumber;将浏览器跳转至 result.redirectUrl(redirectionType 为 2 时执行 clientScript);returnUrl 仅作 UX,回调需用自身 callbackUrl 作为前缀验签、返回 HTTP 200,再以 GET Query 复核;status 为 1 且 referenceCode、transactionNumber、金额、币种、环境一致时幂等结算。GET 请求签名方式为不含查询串的 URL 加排序 JSON 查询参数(数字不加引号)。
适用场景:马来西亚支付网关的 PHP/后端集成、回调处理、退款、循环扣款与出款流程;签名调试可用 staging 后台的 Signature Validator 工具。
限制与注意:密码、密钥与令牌仅限服务端;不得凭 returnUrl 或前端状态标记已支付;签名使用原始 UTF-8,仅做 JSON 必需转义,递归去除 null 但保留空字符串;仅当渠道 isProviderHostChannel 为 true 时传 providerChannelId;referenceCode 每次支付尝试唯一(最长 50)且回调处理需幂等;退款仅限成功交易,全额退款省略金额,reason 必填,不支持跨境退款;循环扣款(仅信用卡与 TNG)与出款需商务审批;staging 与 production 的渠道 ID 不同(如 TNG staging 10、production 7),出款渠道 staging 15、production 9;无 callbackUrl 则无回调,需轮询 Query。回调重试计划、IP 白名单、时间戳容差、returnUrl 参数与限流官方文档暂未提供。