申请支付令牌

2024-11-22 00:47

POST /v1/authorizations/applyToken

使用以下方式之一调用此接口来实现不同的功能：

将成功调用 授权咨询 接口获得的 authCode 用于此接口，来获取访问令牌，该令牌将在发起代扣时使用。
当现有访问令牌即将过期时，使用此接口通过刷新令牌获取新的访问令牌。

结构

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

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

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

入参

grantType String REQUIRED

此接口具体实现的功能。有效值包括：

AUTHORIZATION_CODE：当你想要获取访问令牌时，使用此值。成功调用此接口后，你可以获取访问令牌。
REFRESH_TOKEN：每个访问令牌都有一个由 accessTokenExpiryTime 指定的有效期。当你的访问令牌即将过期且需要获取新访问令牌时，使用此值。成功调用此接口后，你可以获取新访问令牌。

customerBelongsTo String REQUIRED

客户选择的支付方式。参见支付方式以检查有效值。

更多信息：

最大长度：64 字符

authCode String

用于获取访问令牌的授权码。此字段的值从支付方式返回的重构后的跳转链接中获取。

注意：当 grantType 的值为 AUTHORIZATION_CODE 时，指定此字段。

更多信息：

最大长度：64 字符

refreshToken String

刷新令牌，用于在访问令牌即将过期时获取新的访问令牌。刷新令牌从成功调用的 申请支付令牌 接口的响应中获取。

注意：当 grantType 的值为 REFRESH_TOKEN 时，指定此字段。

更多信息：

最大长度：128 字符

merchantRegion String

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

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

更多信息：

最大长度：2 字符

出参

result Result REQUIRED

表示此接口调用是否成功。如果调用成功，您就能获取访问令牌。

Show child parameters

accessToken String

用于访问相应用户资源范围的访问令牌。

注意：此字段在接口调用成功时返回。

更多信息：

最大长度：128 字符

accessTokenExpiryTime Datetime

访问令牌的过期时间。访问令牌过期后，您将无法使用它从用户的账户中扣款。

注意：当 accessToken 返回时，此字段返回。

更多信息：

值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

refreshToken String

刷新令牌，用于在访问令牌即将过期时获取新的访问令牌。

注意：当支付方式支持刷新令牌时，将返回此字段。如果未返回此字段，则表示访问令牌的有效期相对较长。

更多信息：

最大长度：128 字符

refreshTokenExpiryTime Datetime

刷新令牌的过期时间。刷新令牌过期后，您将无法再使用它获取新的访问令牌。

注意：当 refreshToken 返回时，此字段返回。

更多信息：

值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

userLoginId String

用户在支付方式中注册时使用的登录 ID。登录 ID 可以是用户的电子邮件地址或电话号码，返回给 Alipay+ 支付方式时会被掩码处理。此字段可以通知商家哪些用户已注册。

注意：当 result.resultCode 为 SUCCESS 且 授权咨询 接口中 scopes 字段的值为 AGREEMENT_PAY 时，此字段将返回。

更多信息：

最大长度：64 字符

extendInfo String

扩展信息。

注意：当存在扩展信息时，此字段返回。

更多信息：

最大长度：2048 字符

API Explorer

示例代码沙箱运行

请求

URL

Case

Get accessToken with authCode

请求体

响应

Case

Touch'n Go

Case description

If you apply for the access token of Touch'n Go, the following response is returned:

响应体

结果处理逻辑

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

如果 result.resultStatus 的值为S，访问令牌获取成功。使用访问令牌访问相应的用户资源范围。
如果 result.resultStatus 的值为U，未获取到访问令牌。通过再次调用此接口重试过程。
如果 result.resultStatus 的值为F，未获取到访问令牌。检查错误代码并采取相应措施。然后再次调用此接口重试过程。

结果码

结果码	值	结果码信息	行动建议
SUCCESS	S	成功	授权已完成。请存储 accessToken 和其他相关字段。
ACCESS_DENIED	F	访问被拒绝。	详细原因请咨询 Antom 技术支持。
CLIENT_FORBIDDEN_ACCESS_API	F	客户端无权使用此接口。	详细原因请咨询 Antom 技术支持。
INVALID_ACCESS_TOKEN	F	访问令牌已过期、被撤销或不存在。	检查 accessToken 是否正确。如果不正确，请输入正确的值。如果正确，请联系 Antom 技术支持以获取详细原因。
INVALID_API	F	调用的接口无效或未激活。	请联系 Antom 技术支持解决此问题。
INVALID_AUTHCODE	F	授权码无效。	重新发起授权，调用授权咨询接口获取 authcode。如果授权码正确但仍有问题，请联系 Antom 技术支持进行排查。
INVALID_CLIENT_STATUS	F	客户端状态无效。	详细原因请咨询 Antom 技术支持。
INVALID_REFRESH_TOKEN	F	刷新令牌无效。	使用有效的 refreshToken 重新发起请求。如果刷新令牌正确但仍有问题，请联系 Antom 技术支持进行排查。
INVALID_SIGNATURE	F	签名验证失败。请求的私钥与 Antom Dashboard 的公钥不匹配。	检查用于签署请求的私钥是否与 Antom Dashboard 的公钥匹配。以下签名参考信息很有用：请求头中的签名字段如何生成签名
INVALID_SIGNATURE	F	签名验证失败。请求的私钥与 Antom Dashboard 的公钥不匹配。	检查用于签署请求的私钥是否与 Antom Dashboard 的公钥匹配。以下签名参考信息很有用：请求头中的签名字段如何生成签名
KEY_NOT_FOUND	F	找不到 Antom 或商户的私钥或公钥。	检查私钥或公钥是否存在。如果不存在，请在 Antom Dashboard 中上传私钥。
NO_INTERFACE_DEF	F	接口未定义。	检查链接是否正确。请参考接口文档中的端点。
NO_PAY_OPTIONS	F	该接口不支持此支付方式。	检查支付方式是否为 customerBelongsTo 参数的有效值。如果传递的值正确，请联系 Antom 技术支持以获取详细原因。
OAUTH_FAILED	F	OAuth 授权流程失败。	详细原因请咨询 Antom 技术支持。
PARAM_ILLEGAL	F	缺少必需的参数，或者存在非法参数。例如，非数字输入、无效的日期，或者参数的长度和类型错误。	检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。
PROCESS_FAIL	F	发生了常见的业务失败。	获取 Antom 技术支持前请勿重试。
SYSTEM_ERROR	F	系统错误发生。	获取 Antom 技术支持前请勿重试。
UNKNOWN_CLIENT	F	客户端未知。	详细原因请咨询 Antom 技术支持。
USER_NOT_EXIST	F	用户在支付方式端不存在。	详细原因请咨询 Antom 技术支持。
USER_STATUS_ABNORMAL	F	用户在支付方式端的状态异常。	请联系 Antom 技术支持以了解具体原因。
AUTH_IN_PROCESS	U	授权仍在处理中。	请持续调用此接口，直到收到最终结果状态。
REQUEST_TRAFFIC_EXCEED_LIMIT	U	请求流量超过限制。	再次调用接口来解决问题。如果问题未解决，请联系 Antom 技术支持。
UNKNOWN_EXCEPTION	U	由于未知原因，接口调用失败。	再次调用接口来解决问题。如果问题未解决，请联系 Antom 技术支持。