Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

授权咨询

POST /v1/authorizations/consult

使用此接口获取用户授权。成功调用此接口后，您可以获取授权链接并跳转到授权链接以同意授权。同意授权后，支付方式会将用户跳转到一个重构后的跳转链接，该链接包含 authRedirectUrl、authCode 和 authState 的值。例如，跳转链接可能是：https://www.merchant.com/authorizationResult?authCode=3AB2F588D14B43238637264FCA5AAF35&authState=663A8FA9-D836-48EE-8AA1-1FF682989DC7。

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息，有关报文头的结构信息，请参阅：


注意：将每个字段（除数组外）的数据类型设置为字符串。这意味字段值必须使用双引号（" "）括起来。例如：

  • 如果字段的数据类型为整数属性，且其值为 20，设置为 "20"。
  • 如果字段的数据类型为布尔属性，且其值为 true，设置为 "true"。

入参

customerBelongsTo String  REQUIRED

用户使用的支付方式。 请参见支付方式以查看有效值。  

更多信息：

  • 最大长度：64 字符

authClientId String  

用户授予二级商户的专属 ID，以用于资源访问权限。该值由收单机构指定，并需要在 Antom 上注册。

注意：

  • 如果您是具有二级商户的收单机构，请指定此字段。
  • 对于 Alipay+ 支付方式，此字段的值与 支付（代扣）接口中 referenceMerchantId 的值相同。

更多信息：

  • 最大长度：64 字符

authRedirectUrl URL  REQUIRED

用户在同意授权后会跳转到此链接。此值由商户提供。

更多信息：

  • 最大长度：1024 字符

scopes Array<String>  REQUIRED

授权访问的资源范围。有效值包括：  

  • BASE_USER_INFO: 表示可以获取的专属用户 ID。
  • USER_INFO: 表示可以获取完整的用户信息，例如用户名、头像和其他用户信息。
  • AGREEMENT_PAY: 表示用户同意授权代扣，以便商户可以使用访问令牌从用户的账户中进行自动扣款。

更多信息：

  • 最多可包含元素个数：4

authState String  REQUIRED

由商户生成的专属 ID，用于表示咨询请求。此字段需与用户同意授权时跳转链接中的字段保持一致。

更多信息：

  • 最大长度：256 字符

terminalType String  REQUIRED

商户服务适用的终端类型。有效值包括：

  • WEB: 客户端终端类型为通过网络浏览器打开的网站。
  • WAP: 客户端终端类型为通过移动浏览器打开的 HTML 页面。
  • APP: 客户端终端类型为移动应用程序。
  • MINI_APP: 商户端的终端类型为手机上的小程序。

osType String  

操作系统类型。有效值为：

  • IOS: 表示操作系统为苹果的 iOS。
  • ANDROID: 表示操作系统为谷歌的 Android。

注意：当 terminalType 为 APP 、 WAP 或 MINI_APP 时，此字段是必需的。

osVersion String  

操作系统版本。

​注意​：当 terminalType 的值为 APP 或 WAP 且您拥有此信息时，指定此参数。提供此信息可以优化用户的支付体验。

更多信息：

  • 最大长度：16 字符

merchantRegion String  

商户或二级商户开展业务的国家或地区。此参数遵循 ISO 3166 国家代码 标准，目前仅支持 US , JP , PK , SG。

注意：使用全球收单网关（GAGW）产品时，此字段是必需的。

更多信息：

  • 最大长度：2 字符

recurringPayment Boolean  

表示发起的签约代扣是否为定期支付。有效值为：

  • true：表示发起的签约代扣是定期支付。
  • false：表示发起的签约代扣不是定期支付。

注意：当签约的支付方式为 PAYPAY 时指定此参数。

出参

result Result  REQUIRED

表明此接口是否调用成功。如果接口调用成功，可以获取授权链接。

Show child parameters

schemeUrl URL  

应用安装完成后，用于在 Android 或 iOS 操作系统中打开应用的 URL scheme。

注意：当 result.resultCode 的值为 S 时，需要返回 schemeUrl、applinkUrl 和 normalUrl 中的至少一个。

更多信息：

  • 最大长度：2048 字符

applinkUrl URL  

应用安装完成后，用户将跳转到打开应用的链接，或者安装失败时，打开 WAP 页面。对于 Android 系统，该链接是 Native App Link。对于 iOS 系统，该链接是 Universal Link。

注意：当result.resultCode的值为S时，需要返回schemeUrl、applinkUrl和normalUrl中的至少一个。 

更多信息：

  • 最大长度：2048 字符

appIdentifier String  

Android 包名，用于在 Android 应用中打开收银台页面。

注意：当 result.resultCode 为S且 terminalType 为APP或WAP时，此字段会被返回。

更多信息：

  • 最大长度：128 字符

normalUrl URL  

用户将跳转到默认浏览器或嵌入式 WebView 中的 WAP 或 WEB 页面的链接。

注意：当 result.resultCode 的值为 S 时，需要返回 schemeUrl、applinkUrl 和 normalUrl 中的至少一个。

更多信息：

  • 最大长度：2048 字符

authCodeForm AuthCodeForm  

授权二维码的信息。

注意：当支付方式支持通过扫描二维码进行授权时，此参数将返回。

Show child parameters
API Explorer
示例代码沙箱运行

请求

URL

Payment method
AlipayCN AlipayCN
Terminal type
APP APP
Integration role
请求体

响应

响应体

结果处理逻辑

对于不同的请求结果，需要执行不同的操作。详细信息如下：

  • 如果 result.resultStatus 的值为 S，则响应中的 schemeUrl、applinkUrl 或 normalUrl 字段成功获取了授权链接。商户可以将用户跳转到这个链接，让用户同意授权以授予相应的资源访问权限。
  • 如果 result.resultStatus 的值为 U，则接口调用状态未知。您可以再次调用此接口以重试流程。
  • 如果 result.resultStatus 的值为 F，则未能获取授权链接。通常，这可能是由于系统缺陷或系统故障导致的。检查错误代码并采取相应措施，或联系 Antom 技术支持。

结果码

结果码值结果码信息行动建议
SUCCESSS成功

接口调用成功。从响应中获取 schemeUrl、applinkUrl 或 normalUrl 。

ACCESS_DENIEDF访问被拒绝。

详细原因请咨询 Antom 技术支持。

CLIENT_FORBIDDEN_ACCESS_APIF客户端无权使用此接口。

详细原因请咨询 Antom 技术支持。 

INVALID_ACCESS_TOKENF访问令牌已过期、被撤销或不存在。

检查 accessToken 是否正确。如果不正确，请输入正确的值。如果正确，请联系 Antom 技术支持以获取详细原因。 

INVALID_APIF调用的接口无效或未激活。

请联系 Antom 技术支持解决此问题。 

INVALID_CLIENT_STATUSF客户端状态无效。

详细原因请咨询 Antom 技术支持。

INVALID_SIGNATUREF签名验证失败。请求中使用的私钥与 Antom Dashboard 的公钥不匹配。

检查用于签署请求的私钥是否与 Antom Dashboard 的公钥匹配。以下签名参考信息很有用：

KEY_NOT_FOUNDF找不到 Antom 或商户的私钥或公钥。

检查私钥或公钥是否存在。如果不存在，请在 Antom Dashboard 中上传私钥。

MERCHANT_NOT_REGISTEREDF商户未注册。

请使用注册接口注册商户。如果无法调用注册接口，请联系 Antom 技术支持。

NO_INTERFACE_DEFF接口未定义。

检查链接是否正确。请参考接口文档中的端点。

NO_PAY_OPTIONSF该接口不支持此支付方式。

检查支付方式是否为 customerBelongsTo 参数的有效值。如果传递的值正确，请联系 Antom 技术支持以获取详细原因。

OAUTH_FAILEDFOAuth 授权流程失败。

详细原因请咨询 Antom 技术支持。

PARAM_ILLEGALF缺少必需的参数，或者存在非法参数。例如，非数字输入、无效的日期，或者参数的长度和类型错误。

检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。

PAYMENT_NOT_QUALIFIEDF商户不具备支付资格，可能是因为未注册、未签订自动扣款协议或被禁止支付。

请联系 Antom 技术支持以获取详细原因。

PROCESS_FAILF发生了常见的业务失败。

获取 Antom 技术支持前请勿重试。

RISK_REJECTF因风险控制，请求被拒绝。

提示用户请求被拒绝，因为风险控制失败。

SYSTEM_ERRORF系统错误发生。

获取 Antom 技术支持前请勿重试。

UNKNOWN_CLIENTF客户端未知。

详细原因请咨询 Antom 技术支持。

REQUEST_TRAFFIC_EXCEED_LIMITU请求流量超过限制。

再次调用接口来解决问题。如果问题未解决，请联系 Antom 技术支持。

UNKNOWN_EXCEPTIONU由于未知原因，接口调用失败。

再次调用接口来解决问题。如果问题未解决，请联系 Antom 技术支持。