PAYATHON 2026

IOT小程序如何调用API实现蜻蜓设备刷脸支付？

支付小周

结论

不是只能通过 my.ix.startApp 实现。

蜻蜓设备上的刷脸支付通常有两种接入方式：

  1. IoT 小程序通过 my.ix.startApp 拉起设备内置的收银应用。这种方式适合直接使用蜻蜓标准收银界面的场景。
  2. 商户服务端先创建支付宝交易，再由小程序调用支付能力完成付款。具体可以使用 my.tradePay，也可以调用设备运行环境提供的专用支付 API。

蜻蜓有不同的设备型号、系统版本和 IoT 小程序运行环境，可用的 API 和参数可能并不相同。不能只根据普通支付宝小程序文档判断设备是否支持某个接口，需要以目标设备对应的开放平台文档、基础库版本和实际权限为准。

为什么不能只看 my.ix.startApp

my.ix.startApp 用于启动设备上的原生应用。它不是通用的订单创建接口，也不会替商户完成签名、金额校验或异步通知处理。

一套完整的刷脸支付流程至少包含三个环节：

  • 商户服务端创建交易；
  • 蜻蜓设备打开支付或收银页面；
  • 商户服务端接收支付通知，并主动查询交易结果。

即使前端使用 my.ix.startApp，订单创建和最终状态确认也应由商户服务端完成。

推荐的接入流程

1. 完成应用和设备侧配置

接入前需要确认：

  • 支付宝应用已经开通相应的当面付或刷脸支付能力；
  • IoT 小程序已绑定对应的应用、商户和蜻蜓设备；
  • 目标设备支持计划使用的 API；
  • 小程序基础库版本满足要求；
  • 支付接口需要的权限、白名单或产品签约已经生效；
  • 服务端已经配置支付宝公钥、应用私钥和异步通知地址。

不同支付产品的签约要求可能不同。如果控制台中没有相应的能力入口，需要向支付宝服务商或对应的产品支持渠道确认。

2. 由服务端创建交易

应用私钥不能保存在小程序中，支付宝签名也不能直接在设备端拼装。

小程序只需向商户自己的服务端提交商品、门店和业务订单信息：

my.request({
  url: 'https://merchant.example.com/api/orders',
  method: 'POST',
  data: {
    merchantOrderNo: 'ORDER_20260913_0001',
    subject: '门店消费',
    amount: '10.00',
    storeId: 'STORE_001'
  },
  success(res) {
    if (!res.data || !res.data.success) {
      my.alert({ content: '创建订单失败' });
      return;
    }

    startPayment(res.data);
  },
  fail() {
    my.alert({ content: '网络异常，请稍后重试' });
  }
});

服务端负责：

  1. 校验商品和实际应付金额；
  2. 生成唯一的商户订单号；
  3. 调用支付宝服务端交易接口；
  4. 保存支付宝交易号与商户订单号的对应关系；
  5. 将前端支付需要的受控参数返回给小程序。

服务端具体调用哪个交易接口，取决于已经签约的支付产品，不能只根据设备名称判断。

方式一：通过 my.ix.startApp 拉起内置收银应用

如果设备提供内置的刷脸收银应用，可以使用 my.ix.startApp 启动：

function startPayment(order) {
  my.ix.startApp({
    appName: order.appName,
    params: order.startParams,
    success(result) {
      queryPaymentResult(order.merchantOrderNo);
    },
    fail(error) {
      console.error('启动收银应用失败', error);
      my.alert({
        content: '暂时无法启动刷脸支付'
      });
    }
  });
}

其中的 appName、params 和回调字段必须按照目标设备的接口文档填写。不同蜻蜓系统版本可能使用不同的应用标识和参数结构，不能自行将它们假定为固定值。

success 通常只能说明原生应用已经成功拉起，或者调用过程正常返回，不一定表示资金支付成功。最终支付结果仍需由服务端查询确认。

这种方式适用于以下情况：

  • 需要使用设备的标准收银界面；
  • 不希望自行处理刷脸采集页面；
  • 当前设备明确开放了对应的原生应用；
  • 可以接受支付过程中从 IoT 小程序切换到系统应用。

方式二：使用 my.tradePay 支付已有交易

如果蜻蜓的 IoT 小程序环境支持 my.tradePay，服务端创建交易后，可以将允许传递给前端的交易凭证返回给小程序，再发起支付：

function startPayment(order) {
  my.tradePay({
    tradeNO: order.tradeNo,
    success(result) {
      console.log('支付调用返回', result);
      queryPaymentResult(order.merchantOrderNo);
    },
    fail(error) {
      console.error('支付调用失败', error);
      my.alert({
        content: '支付未完成，请重新尝试'
      });
    }
  });
}

tradeNO 的来源、可以使用的交易产品，以及设备是否会自动进入刷脸流程，都取决于接入的支付宝支付产品和蜻蜓运行环境。

如果设备文档提供了专用的 IoT 支付 API，应按照该文档调用，不要强行套用 my.tradePay。专用接口的名称、参数和支持版本可能变化，没有明确的设备文档时不应写死。

支付结果必须由服务端确认

无论前端采用哪种调用方式，都不能只根据前端回调更新订单状态。

支付页面返回后，前端可以请求商户服务端查询结果：

function queryPaymentResult(merchantOrderNo) {
  my.request({
    url: 'https://merchant.example.com/api/orders/status',
    method: 'GET',
    data: {
      merchantOrderNo
    },
    success(res) {
      const status = res.data && res.data.status;

      if (status === 'PAID') {
        my.alert({ content: '支付成功' });
      } else if (status === 'CLOSED') {
        my.alert({ content: '订单已关闭' });
      } else {
        my.alert({ content: '支付结果确认中，请稍后查询' });
      }
    },
    fail() {
      my.alert({
        content: '暂时无法确认支付结果，请勿重复付款'
      });
    }
  });
}

服务端还应处理：

  • 支付宝异步通知验签；
  • 商户订单号和金额校验；
  • 主动查询交易；
  • 对重复通知做幂等处理；
  • 关闭超时未支付的订单；
  • 撤销、退款和异常订单补偿。

前端出现取消、超时或网络错误时，交易仍可能已经完成。此时不能立即创建新订单并再次扣款。

刷脸核身和刷脸支付不是同一个能力

设备提供的人脸核身、身份确认或会员识别 API，不能直接当作支付接口使用。

两者的用途不同：

  • 刷脸核身用于确认用户身份；
  • 刷脸支付用于完成资金交易；
  • 核身成功不等于付款成功；
  • 不能自行获取人脸信息并绕过支付宝支付流程。

处理人脸数据时，还需遵守授权提示、用途限定、数据最小化和隐私保护要求。除非接口文档明确允许，否则不要在小程序或商户服务端保存原始人脸图像和生物特征数据。

接入时容易出现的问题

前端回调成功，但订单仍未支付

前端的成功回调不一定代表交易成功。最终状态应通过服务端异步通知或主动查询确认。

my.ix.startApp 调用失败

可以重点检查：

  • appName 是否与设备文档一致；
  • 参数是否符合内置应用的要求；
  • 当前设备是否安装或开放了该应用；
  • 小程序是否具备调用权限；
  • 基础库与设备系统版本是否匹配。

普通支付宝小程序可以调用，蜻蜓上却不可用

普通支付宝小程序和 IoT 小程序使用的运行容器并不完全相同。某个 API 出现在通用文档中，不代表所有蜻蜓设备都支持它。

可以先检测接口是否存在，并准备相应的降级提示：

if (typeof my.tradePay === 'function') {
  startPayment(order);
} else {
  my.alert({
    content: '当前设备版本暂不支持该支付方式'
  });
}

这种检测只能判断方法是否存在，不能代替产品签约、权限检查和真实支付验证。

建议的最终方案

如果要快速接入蜻蜓的标准刷脸收银流程，可以采用：

IoT 小程序创建业务订单
→ 商户服务端创建支付宝交易
→ my.ix.startApp 拉起设备内置收银应用
→ 用户完成刷脸支付
→ 服务端接收异步通知并查询交易
→ IoT 小程序展示最终结果

如果目标设备明确支持 my.tradePay 或专用 IoT 支付 API，也可以采用：

IoT 小程序创建业务订单
→ 商户服务端创建支付宝交易
→ 小程序调用支付 API
→ 设备进入支付宝刷脸支付流程
→ 服务端确认最终交易状态

my.ix.startApp 只是拉起内置收银能力的一种方式，并非唯一的支付架构。具体方案要根据设备型号、系统版本、基础库、已签约产品和开放权限确定。上线前至少需要在真机上验证正常支付、用户取消、支付超时、断网、重复点击、已付款未回跳和订单退款等场景。

备注：内容仅供参考。