SuperAPI AI 工具集

setup-antom

编程与开发

查看项目

更新于 11-17 02:09

技能介绍

用途

该技能面向 Antom(Ant International)在马来西亚的商户支付集成工作,用于搭建、构建、调试、审查和讲解 Antom 支付集成。它汇集了环境、签名、结账、支付操作、通知、错误码等参考文件,并提供从下单到结算的完整工作流说明。

参考资料

  • 先阅读 references/antom-api.md,其中包含环境、域名、请求头、签名方法、幂等、金额规则、完整端点目录及其它参考文件的索引。
  • references/antom-checkout.md:pay、createPaymentSession、consult 的字段表与集成模式(Checkout Page、Element、API-only)。
  • references/antom-payment-ops.md:inquiryPayment、capture、cancel、refund、inquiryRefund 的字段与规则。
  • references/antom-notifications.md:notifyPayment、notifyCapture、notifyRefund 字段、验签、确认响应体与重试。
  • references/antom-errors.md:各 API 的结果与错误码;references/antom-codes.md:支付方式枚举、FPX 银行代码、卡品牌、状态及马来西亚方式限制。
  • references/account-setup.md:入驻、密钥、沙箱、上线、结算与定价位置;references/source-map.md:定位对应官方页面。

主要能力与核心流程

  1. 识别环境:沙箱(client ID 以 SANDBOX_ 开头,路径 /ams/sandbox/api/...)或生产(/ams/api/...)。
  2. 识别集成模式:托管 Checkout Page、嵌入式 Checkout Page、Payment Element 或 API-only(使用 paymentMethodType 调用 pay)。
  3. 确认 Dashboard 设置:client ID、网关域名、商户密钥对、Antom 公钥、通知 URL、已启用支付方式、结算币种。
  4. 在调用 Antom 前,用自有 paymentRequestId 创建本地待支付订单。
  5. 使用私钥(RSA256)对每个请求签名,并用 Antom 公钥验证每个响应签名。
  6. 服务端调用 createPaymentSession(Checkout Page 或 Element)或 pay(API-only);重定向到 normalUrl / applinkUrl / schemeUrl,或将 paymentSessionData 传给客户端 SDK。
  7. paymentRedirectUrl 仅用于展示,绝不能凭浏览器返回标记为已支付。
  8. 对原始请求体验证 notifyPayment 签名,然后返回固定 SUCCESS 确认。
  9. 检查 paymentRequestId、paymentId、金额、币种和 result.resultStatus 后做幂等结算;卡、Apple Pay 和 Google Pay 仅在 capture 成功后发货。
  10. 通知延迟或缺失时回退到 inquiryPayment。

关键事实

  • 所有 API 为 POST + JSON,版本 v1,路径 https://<domain>/ams/api/v1/...。
  • 亚洲域名:https://open-sea-global.alipay.com(亦可用 https://open-sea.alipay.com),以 Dashboard 显示为准。
  • 沙箱在线支付路径为 /ams/sandbox/api/<endpoint>;官方 SDK 在 client ID 以 SANDBOX_ 开头时会把 /ams/api 改写为 /ams/sandbox/api。
  • 必需请求头:client-id、request-time、signature;Content-Type: application/json; charset=UTF-8 可选。
  • 对 POST <http-uri>\n<client-id>.<request-time>.<request-body> 使用 SHA256withRSA 签名,再 base64,再 URL 编码。
  • 签名头格式:algorithm=RSA256, keyVersion=1, signature=<urlencoded-signature>。
  • 响应验签使用 <client-id>.<response-time>.<raw-response-body>;通知验签使用 <client-id>.<request-time>.<raw-notify-body>。
  • 金额为最小单位的字符串;MYR 两位小数,RM13.14 写作 "1314"。
  • 一次性支付使用 productCode CASHIER_PAYMENT;会话的 productScene 为 CHECKOUT_PAYMENT 或 ELEMENT_PAYMENT。
  • 马来西亚枚举:ONLINEBANKING_FPX、TNG、BOOST、GRABPAY_MY、SHOPEEPAY_MY、CARD。
  • 默认支付超时 14 分钟;支付会话默认 1 小时。
  • 通知确认体固定为 {"result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"}},无需签名。
  • 通知重试最长 24 小时,间隔为 0s、2m、10m、10m、1h、2h、6h、15h。
  • API 中设置的通知 URL 会覆盖 Dashboard 值,但 capture 通知以 Dashboard 值为准。
  • 手动 capture 须在授权后 7 天内完成,仅支持全额 capture。
  • 退款为异步;卡退款不会同步返回 S;FPX 退款窗口 180 天,TNG、Boost、GrabPay MY、ShopeePay MY 为 365 天。
  • 费用未在文档中公布,可在 Antom Dashboard > Payments > Payment methods > Price 查看。

使用限制与关键规则

  • 商户私钥与 client ID 必须保留在服务端,使用 <CLIENT_ID>、<MERCHANT_PRIVATE_KEY>、<ANTOM_PUBLIC_KEY> 等占位符。
  • 测试与生产使用不同密钥、client ID 和 URL,禁止混用。
  • 必须在原始请求体字节上验签,不能先解析再重新序列化 JSON。
  • 必须对请求头中发送的确切 request-time 字符串签名。
  • result.resultStatus U 并非失败;PAYMENT_IN_PROCESS 应重定向,其它 U 按文档进行 inquiry 或使用新 paymentRequestId。
  • 不得在金额、币种或支付方式变更后复用 paymentRequestId(REPEAT_REQ_INCONSISTENT)。
  • 退款使用 notifyPayment 中的 paymentId;Antom 页面上的卡重试可能产生新 paymentId。
  • 返回 REFUND_IN_PROCESS 的退款不得重试,应使用 inquiryRefund 查询。
  • 通知处理必须幂等,记录已处理通知并忽略重复项。
  • 声明生产确定性前,应与 Antom 确认线上方式可用性、收单主体、限额、结算周期与定价。

适用场景

适用于马来西亚商户接入 Antom 一次性支付、托管或嵌入式 Checkout Page、Payment Element、仅 API 支付,以及支付查询、capture、取消、退款和异步通知处理的开发、调试、审查与讲解。