Antom 收银台支付集成 & 业务回调实现

Antom 收银台支付集成 & 业务回调实现

2026-02-10技术文章1 阅读

结合本地实现和antom支付.md的官方文档示例，给出一个完善的 Antom 收银台支付对接实施总结，包括商品/网上付款区分、回调识别与业务落地的完整闭环，适合放在你的项目文档里：

Antom 收银台支付集成 & 业务回调实现

1. 接口网关配置

注意：沙箱不同地区必须用正确的 GATEWAY 接口！

  • 新加坡（sea）：

    
const GATEWAY = process.env.ver === "Production"

  ? "https://open-sea-global.alipay.com/ams/api/v1/payments/createPaymentSession"

  : "https://open-sea-global.alipay.com/ams/sandbox/api/v1/payments/createPaymentSession";

  • 保证币种、地区参数与收银台接口保持一致！

2. 发起支付时请求体示例

以 Antom 官方为基础，结合业务区分“商品”和“网上付款”：


{

  "order": {

    "buyer": {

      "referenceBuyerId": "userId"

    },

    "goods": [

      {

        "goodsBrand": "DaDate",

        "goodsCategory": "goods/product",

        "goodsImageUrl": "https://example.com/image.png",

        "goodsName": "商品标题",

        "goodsQuantity": "1",

        "goodsSkuName": "SKU说明",

        "goodsUnitAmount": {

          "currency": "HKD",

          "value": "1200"

        },

        "goodsUrl": "https://yourGoodsUrl",

        "referenceGoodsId": "yourGoodsId"

      }

    ],

    "orderAmount": {

      "currency": "HKD",

      "value": "1200"

    },

    "orderDescription": "商品说明",

    "referenceOrderId": "202311011234567", 

  },

  "paymentAmount": {

    "currency": "HKD",

    "value": "1200"

  },

  "paymentNotifyUrl": "https://yourdomain.com/antom/callback?type=goods&orderNum=202311011234567",

  "paymentRedirectUrl": "https://yourdomain.com/pay-success?type=goods&orderNum=202311011234567",

  "paymentRequestId": "平台唯一支付请求号",  // 一般用UUID或雪花ID

  "productCode": "CASHIER_PAYMENT",

  "productScene": "CHECKOUT_PAYMENT"

}

网上付款类型类似，只需：

  • goodsCategory 换成 "online payment/service"

  • type=goods 改成 type=online

  • 传不同的订单号

3. 区分商品/网上付款的核心点

  • 发起支付时： 在 paymentNotifyUrl、paymentRedirectUrl 加 type（goods/online）和 orderNum 参数

  • 数据库保存：订单号、订单类型（goods/online）、金额信息等

4. 回调处理（/antom/callback）

核心推荐做法：仅通过 URL 上的 type 与 orderNum 参数识别订单！


const { type, orderNum } = request.query;

if (!type || !orderNum) {

  // 必要参数校验

  return reply.status(400).send("Invalid callback, missing type or orderNum");

}



// 1. 通过 type 路由至正确表

let orderInfo = null;

if (type === 'goods') {

  orderInfo = await collection("web_order").findOne({ orderNum });

} else if (type === 'online') {

  orderInfo = await collection("web_online_pay").findOne({ orderNum });

}

// ...正常的支付成功落库/积分处理...

无需依赖 referenceOrderId，Antom 回调不会回传；也不用再存 paymentRequestId。

5. 回调验签处理

  • 按官方文档，理应对 Antom 回调做签名验签

  • 项目中通过 signature、request-time、client-id 和原始 body 字符串验签（如遇问题可暂时放宽）

  • 代码推荐（伪代码）：

    
// 获取 signatureHeader, requestTime, clientId, rawBody

// 先试 body，再试 clientId.requestTime.body 方式做 RSA256 验证

// 生产环境建议验签不过直接 400 拒绝

6. 回调类型说明

Antom 的回调一般会发两次：

  • PAYMENT_RESULT：预授权/支付确认（用来做订单状态变更即可）

  • CAPTURE_RESULT：资金实际到帐（建议如果订单已状态已更，就不用重复处理）

7. 结论—推荐实践

  • 订单类型/单号唯一性请务必保障！直接用 URL 参数分流即可

  • 回调中若验签失败，建议打印日志便于后期定位

  • 如后续 Antom 支持 webhook 原始 body，建议切换为原始验证

例子小结（伪代码）


// 支付时

paymentNotifyUrl: `https://yourdomain.com/antom/callback?type=goods&orderNum=${orderNum}`



// 回调时

const { type, orderNum } = request.query

if (type === 'goods') { ... }

else if (type === 'online') { ... }

只要按此规范实现，业务区分、回调查单、安全落库，一条龙无遗漏，Antom 支付落地就没有问题。

如需放入项目的 antom 对接文档，这份总结可以直接复制粘贴！

本文由萧兮的博客原创发布，欢迎转载，转载务必保留原文链接。

萧兮的博客：https://www.20010515.xyz · 原文：https://www.20010515.xyz/posts/3a76de23-41f1-4b7d-b9a2-a08446cc70cd