PAYATHON 2026

蜻蜓IoT设备推荐会员卡提示必填字段未授权

支付老李

结论

这个问题通常不是因为 OPEN_FORM_FIELD_CITY 被设为必填，而是会员卡模板包含了当前商户或第三方应用无权采集的开卡字段。

即使字段配置为 optional，蜻蜓 IoT 的“支付后推荐”在校验会员卡时，仍可能检查模板涉及的所有用户信息字段。页面提示“必填字段没有授权”是统一错误文案，不一定表示 API 中的 required=true。

解决办法有两种：为实际创建模板的应用和商户开通相应的字段权限，或从模板中删除未授权字段。之后重新创建模板、生成领卡链接，再配置支付后推荐。应用后来获得授权后，已经创建的旧模板不一定会自动更新，建议新建模板进行验证。

原因分析

通过 alipay.marketing.card.template.create 等接口创建会员卡模板时，需要分清三个概念：

  • 字段是否显示在开卡表单中；
  • 用户是否必须填写该字段；
  • 应用或商户是否有权采集该字段。

optional 只表示用户开卡时可以不填，并不表示应用可以在未获授权的情况下配置或采集该字段。

蜻蜓设备的支付后推荐是另一个投放入口，通常会重新校验会员卡模板、领卡链路和字段权限。因此，普通领卡页面可以生成或打开，不代表该模板一定符合 IoT 投放要求。

在 ISV 场景中，还要核对授权主体。会员卡所属商户、调用接口的应用，以及支付宝开放平台中的字段权限，需要保持一致并具有有效的授权关系。常见问题有：

  • 第三方应用没有获得 OPEN_FORM_FIELD_CITY 对应的信息采集权限；
  • 商户授权应用调用会员卡接口时，没有同时授权相关开卡字段；
  • 创建模板使用的 app_id，与生成领卡链接或配置蜻蜓推荐时使用的应用不一致；
  • 模板是在获得授权前创建的，之后仍保留旧的字段配置或校验状态；
  • 页面把各种字段权限错误统一显示为“必填字段没有授权”。

处理步骤

1. 确认触发问题的具体字段

先查询或检查会员卡模板配置，确认开卡表单中是否确实只有：

OPEN_FORM_FIELD_CITY

还要检查平台自动补充的字段、业务字段和历史配置。不能只看前端表单显示的内容，应以模板查询接口返回的数据为准。

如果删除 OPEN_FORM_FIELD_CITY 后无法生成领卡链接，需要继续确认“无字段不能生成链接”究竟是接口规则、领卡页面的配置要求，还是调用参数不完整。不要为了绕过限制而随意添加手机号、姓名、身份证号等权限要求更高的字段。

2. 检查应用与商户授权

以创建模板时实际使用的第三方应用为准，在支付宝开放平台和商户会员卡相关管理页面检查：

  • 应用是否具备创建会员卡模板和领卡所需的能力；
  • 商户是否已将相应能力授权给该 ISV 应用；
  • OPEN_FORM_FIELD_CITY 对应的用户信息采集权限是否已申请并生效；
  • 授权对应的商户账号、应用 app_id 和模板归属是否一致；
  • 应用授权是否已过期、被撤销或曾经重新授权。

页面中的“点此自主申请”通常会进入字段权限申请入口。入口名称和审核要求可能随开放平台后台调整，请以当前控制台显示为准。

3. 核对第三方应用调用身份

ISV 调用接口时，应使用第三方应用身份，并携带该商户对应的有效授权信息。不要混用自用型应用、公钥证书或其他商户的授权令牌。

示意代码如下，具体 SDK 方法名请以当前支付宝开放平台 SDK 为准：

AlipayMarketingCardTemplateCreateRequest request =
    new AlipayMarketingCardTemplateCreateRequest();

request.setBizContent(templateJson);

// ISV 场景应使用目标商户授权给第三方应用的有效 app_auth_token
AlipayMarketingCardTemplateCreateResponse response =
    alipayClient.execute(request, null, appAuthToken);

if (!response.isSuccess()) {
    throw new IllegalStateException(
        response.getCode() + ": " + response.getSubMsg()
    );
}

需要重点记录并核对：

app_id
app_auth_token 对应的商户
template_id
接口返回的 code
接口返回的 sub_code
接口返回的 sub_msg

不要在日志或工单中提交完整的 app_auth_token、应用私钥或用户敏感信息。

4. 使用最小字段配置重新创建模板

字段权限生效后，建议重新创建一个只包含必要字段的测试模板。下面的示例仅用于说明配置思路，字段结构和参数层级应以实际接口文档为准：

{
  "open_form_field_list": [
    {
      "common_field_name": "OPEN_FORM_FIELD_CITY",
      "required": "false"
    }
  ]
}

如果当前接口要求布尔值而不是字符串，应按照接口定义传递：

{
  "required": false
}

不要直接照搬示例修改生产请求。不同接口版本或 SDK 对字段名称、类型和嵌套结构的定义可能不同。

新模板创建成功后，按以下顺序验证：

  1. 查询模板，确认字段配置符合预期；
  2. 使用同一应用和同一商户授权生成领卡链接；
  3. 在普通环境中测试领卡流程；
  4. 在蜻蜓 IoT 后台配置支付后推荐；
  5. 确认页面不再提示字段未授权。

5. 仍然报错时提交完整链路信息

如果字段权限已经生效，但新建模板仍然报错，建议向支付宝开放平台技术支持提交工单。至少提供：

  • 第三方应用 app_id；
  • 商户 PID，并做好脱敏；
  • 会员卡 template_id；
  • 模板查询结果中的开卡字段配置；
  • 字段权限申请状态截图；
  • 蜻蜓设备后台的错误截图；
  • 创建模板和生成领卡链接时的接口错误码；
  • 问题发生时间；
  • 是否使用了商户授权令牌。

此时，问题可能出在 IoT 投放侧的模板校验或权限状态同步。仅修改 required 属性通常无法解决。

注意事项

  • optional 表示“用户可以不填写”，不表示“不需要字段授权”。
  • 授权应配置在实际创建模板并代表商户调用接口的第三方应用上。
  • 获得权限后，优先新建模板测试，以免旧模板缓存或历史配置干扰判断。
  • 不要为了满足领卡链接的生成条件而添加业务不需要的字段。
  • 如果后台没有对应字段的申请入口，应通过开放平台工单确认该字段是否对当前应用类型开放。
  • “必填字段没有授权”可能是通用错误文案，最终应结合模板查询结果、应用权限状态和接口错误码判断。

备注：内容仅供参考。