PAYATHON 2026

alipay.trade.customs.declare 商户如何授权第三方应用

支付小周

结论

alipay.trade.customs.declare 是支付宝跨境支付场景中的海关申报接口,不属于第三方应用后台可以直接搜索和绑定的普通开放产品。

商户开通海关报关,只能说明商户具备报关资格,不代表第三方应用自动取得该接口的调用权限。如果在“第三方应用 → 产品绑定”中找不到“海关报关”或“跨境支付”,一般表示该能力不支持自助绑定。此时需要联系支付宝跨境业务经理或开放平台技术支持,确认第三方应用是否可以调用,并配置相应权限。

“当面付”“电脑网站支付”等其他支付产品与该接口的授权无关,随意绑定这些产品无法解决 alipay.trade.customs.declare 的权限问题。

为什么会提示“商户未授权当前接口”

第三方应用代商户调用该接口,必须同时满足以下条件:

  1. 商户已经签约并开通跨境支付、海关报关等相关能力。
  2. 第三方应用拥有 alipay.trade.customs.declare 的调用权限。
  3. 商户授权第三方应用时,授权范围包含该接口对应的产品能力。
  4. 请求中使用了该商户授权生成的有效 app_auth_token。
  5. 报关主体、支付交易与被授权商户之间的关系符合支付宝的业务配置。

所以,即使商户可以自行报关,第三方应用仍可能因缺少接口权限而收到“商户未授权当前接口”的提示。

处理步骤

1. 确认接口所属业务能力

先在支付宝开放平台查看 alipay.trade.customs.declare 的接口文档,重点核对以下内容:

  • 当前应用类型是否支持该接口;
  • 接口是否允许第三方应用代调用;
  • 接口所属产品或业务能力是否与跨境支付、海关报关有关;
  • 接入是否需要邀约、人工审核或线下签约。

如果文档中没有第三方应用的自助接入入口,仅通过“产品绑定”无法完成授权。

2. 核对商户签约状态

请商户确认,开通报关能力的支付宝账号与实际支付交易的收款账号一致。同时准备以下信息:

  • 商户支付宝账号或商户 PID;
  • 第三方应用 app_id;
  • 接口名称:alipay.trade.customs.declare;
  • 报错信息及支付宝返回的错误码;
  • 对应的支付订单号;
  • 当前使用的授权模式;
  • 商户已开通跨境支付或海关报关能力的凭证。

只有“商户已开通海关报关”的页面截图,有时还不足以证明该能力已经授权给指定的第三方应用。

3. 联系支付宝配置权限

如果在“第三方应用 → 产品绑定”中找不到对应产品,应通过支付宝开放平台工单、跨境业务经理或签约渠道提交申请,并说明:

第三方应用需要代已签约商户调用 alipay.trade.customs.declare,应用后台无法搜索到对应的海关报关或跨境支付产品,请确认该接口是否支持第三方应用,并协助开通或配置接口权限。

请支付宝明确确认以下问题:

  • 该接口目前是否允许第三方应用代调用;
  • 第三方应用应绑定哪个具体产品;
  • 是否需要加入白名单;
  • 商户是否需要重新授权应用;
  • 是否只能由商户自研应用直接调用。

产品名称和开放方式可能随支付宝开放平台的配置变化,最终应以当前接口文档和支付宝的审核结果为准。

4. 权限开通后重新授权

如果支付宝为第三方应用补充了产品或接口权限,建议商户重新进入授权页面,授权第三方应用并获取新的 app_auth_token。

旧的授权令牌一般不会自动获得后来新增的能力。继续使用旧令牌,仍可能收到“商户未授权当前接口”的提示。

调用示例

第三方应用代商户调用时,需要在请求中传入该商户对应的 app_auth_token:

AlipayClient alipayClient = new DefaultAlipayClient(
    gatewayUrl,
    appId,
    appPrivateKey,
    "json",
    "UTF-8",
    alipayPublicKey,
    "RSA2"
);

AlipayTradeCustomsDeclareRequest request =
    new AlipayTradeCustomsDeclareRequest();

request.setBizContent("""
{
  "out_request_no": "CUSTOMS_202609130001",
  "trade_no": "支付宝交易号",
  "merchant_customs_code": "商户海关备案编号",
  "merchant_customs_name": "商户海关备案名称",
  "amount": "100.00",
  "customs_place": "海关代码"
}
""");

AlipayTradeCustomsDeclareResponse response =
    alipayClient.execute(request, null, appAuthToken);

if (response.isSuccess()) {
    System.out.println(response.getBody());
} else {
    System.out.println(response.getCode());
    System.out.println(response.getSubCode());
    System.out.println(response.getSubMsg());
}

示例字段只用于说明调用方式和授权方式。实际必填字段、字段名称及取值规则,请以当前 alipay.trade.customs.declare 官方接口文档为准。

如果第三方应用没有传入 app_auth_token,或者令牌属于其他商户,即使业务参数填写正确,也无法通过代商户授权校验。

注意事项

  • 商户签约权限、第三方应用接口权限,以及商户对应用的授权,属于三个不同的权限层级,缺少任何一层都可能导致调用失败。
  • 在“产品绑定”中找不到产品,一般无法靠更换搜索关键词解决,需要先确认该能力是否允许第三方应用自助接入。
  • 权限调整后,应让商户重新授权并生成新的 app_auth_token,不要继续使用旧令牌。
  • 不要尝试修改 app_id、PID 或省略 app_auth_token 来绕过授权校验。
  • 排查时应保存支付宝返回的 code、sub_code、sub_msg 和请求流水号,提交工单时一并提供。
  • 如果支付宝确认该接口不支持第三方应用代调用,就只能由已开通报关能力的商户自有应用调用,普通的产品绑定无法解决这一限制。

备注:内容仅供参考。