SuperAPI AI 工具集

setup-axaipay

编程与开发

查看项目

更新于 11-17 03:10

技能介绍

用途

本技能面向 Axaipay(Axai Digital Sdn Bhd)支付网关的集成工作,用于搭建、构建、调试、审查和讲解 Axaipay 支付接入。它要求先阅读参考文档再给出 API 结论或编写集成代码:references/axaipay-api.md 提供端点目录、请求与响应字段、每种签名的精确待签字符串、状态与收单方枚举、银行代码、错误码、测试卡及已知文档冲突;references/account-setup.md 覆盖注册、凭据种类与来源、测试与生产环境、插件、退款、AutoDebit 产品、后台安全与定价;references/source-map.md 用于定位官方页面或 PDF。

主要能力

  • 识别环境:staging(演示账号需向 support@axaipay.com 申请)或 production。
  • 识别接入面:托管支付页、bypass 页(直连 FPX 银行或电子钱包)、服务端二维码(DuitNow QR / Alipay+)、AutoDebit 签约,或商店插件。
  • 调用前先在本地创建待支付订单并生成唯一 mchtTrxnId。
  • 服务端构造签名:按文档顺序拼接字段值,HMAC-SHA512 后用 Base64 编码。
  • 托管页:渲染自动提交的 HTML 表单 POST 到 /gateway/v1/payment;二维码:以表单编码体 POST 到 /trxn/qrcode/generate,携带 x-api-key 与 x-signature 头,然后展示 qrCodePayload。
  • 回调处理:对 backendUrl 的 POST 先核验 11 个响应字段上的签名,再匹配 mchtId、mchtTrxnId、金额与本地订单,在 trxnStatus = 11 时幂等入账。
  • 回调延迟或缺失时,用 /trxn/inquiry(按 trxnId 或 mchtTrxnId)兜底,并同样核验查询响应签名。

关键事实

  • 托管页:staging https://staging.axaipay.my/gateway/v1/payment,production https://secured.axaipay.my/gateway/v1/payment。
  • REST 基址:staging https://api-staging.axaipay.my,production https://api.axaipay.my,路径含 /trxn/qrcode/generate、/trxn/inquiry、/trxn/void、/emandate/v1/inquiry。
  • AutoDebit 签约:https://staging.axaipay.my/gateway/emandate/v1/enrolment 与 https://secured.axaipay.my/gateway/emandate/v1/enrolment。
  • 凭据:商户号 mchtId、签名密钥(HMAC secret)、API key(REST 的 x-api-key 头)。
  • 签名均为对纯拼接值(无分隔符、无字段名)做 HMAC-SHA512 后 Base64 输出。
  • 支付请求串:backendUrl + customerEmail + customerName + customerPhone + mchtId + mchtTrxnId + orderDescription + redirectUrl + txnAmount(URL 仅在发送时参与)。
  • 响应与回调串:mchtId + mchtTrxnId + trxnAcquirer + trxnAmount + trxnBankName + trxnFpxMethod + trxnFpxType + trxnId + trxnPaymentMethod + trxnStatus + trxnTime,值保留空格,不含 trxnBuyerName。
  • bypass 页的 paymentMethod 与 acquirerCode 不参与请求签名。
  • 金额为令吉、两位小数(Decimal(12,2),如 4.25),仅支持 MYR。
  • trxnStatus:1 Created、2 In Processing、3 Pending Authorization、11 Paid、22 Failed、23 Timeout、33 Void、44 Refund、55 Cancel。
  • 默认 redirect 与 backend URL 在开户时登记,请求中的 redirectUrl/backendUrl 可覆盖。
  • staging FPX 测试银行为 B2C_TEST、B2B_TEST;签名检查器为 https://staging.axaipay.my:8888/generate-signature。
  • AutoDebit 签约是一笔 RM1.00 的 FPX 支付(trxnRecurringNo = 0),后续扣款以相同载荷结构回调 backend URL。

使用要点与限制

  • 签名密钥与 API key 只能保存在服务端,表单 POST 只携带签名。
  • 不得仅凭 redirect POST 判定支付成功,须依据经核验的后端回调或查询响应入账。
  • 以常量时间比较签名;按收到的 POST 原值重建待签串,不做裁剪或数字重格式化。
  • 使用与 URL 同环境的密钥,staging 与 production 凭据不同。
  • 入账前核对金额与商户号;mchtTrxnId 复用以 PY022 失败,每次尝试须新生成。
  • 官方 WooCommerce 插件在 redirect 且 trxnStatus = 55 时跳过签名校验,不可据此更新订单,应先查询确认。
  • 后端回调处理器应快速返回 HTTP 200(官方插件返回 OK),所需应答体未在文档中说明。
  • 按 mchtTrxnId 查询存在字段顺序的文档冲突,见 references/axaipay-api.md。
  • 生产可用性结论前,需与 Axaipay 确认启用的支付方式、结算条款与定价。
  • 退款不通过 API 完成,由商户向 support 提交退款申请表。
  • 回调重试策略、应答格式、IP 白名单、限流与 void 响应结构均未文档化,需向 support@axaipay.com 确认。

适用场景

面向在马来西亚接入 Axaipay 的开发者与团队:新接入托管支付页或二维码支付、排查回调与签名问题、审查既有集成安全边界、以及向他人解释该网关的签名与状态机规则。