用途
该技能面向 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:定位对应官方页面。
主要能力与核心流程
- 识别环境:沙箱(client ID 以 SANDBOX_ 开头,路径 /ams/sandbox/api/...)或生产(/ams/api/...)。
- 识别集成模式:托管 Checkout Page、嵌入式 Checkout Page、Payment Element 或 API-only(使用 paymentMethodType 调用 pay)。
- 确认 Dashboard 设置:client ID、网关域名、商户密钥对、Antom 公钥、通知 URL、已启用支付方式、结算币种。
- 在调用 Antom 前,用自有 paymentRequestId 创建本地待支付订单。
- 使用私钥(RSA256)对每个请求签名,并用 Antom 公钥验证每个响应签名。
- 服务端调用 createPaymentSession(Checkout Page 或 Element)或 pay(API-only);重定向到 normalUrl / applinkUrl / schemeUrl,或将 paymentSessionData 传给客户端 SDK。
- paymentRedirectUrl 仅用于展示,绝不能凭浏览器返回标记为已支付。
- 对原始请求体验证 notifyPayment 签名,然后返回固定 SUCCESS 确认。
- 检查 paymentRequestId、paymentId、金额、币种和 result.resultStatus 后做幂等结算;卡、Apple Pay 和 Google Pay 仅在 capture 成功后发货。
- 通知延迟或缺失时回退到 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、取消、退款和异步通知处理的开发、调试、审查与讲解。