Antom, leading provider of tailored payment solutions
Contact Us
Log In

applyToken

POST /v1/authorizations/applyToken

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

  • 将成功调用 consult 接口获得的 authCode 用于此接口，来获取访问令牌，该令牌将在发起令牌支付时使用。
  • 当现有访问令牌即将过期时，使用此接口通过刷新令牌获取新的访问令牌。

结构

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

注意：将每个参数（除数组外）的数据类型设置为字符串，即参数的值必须使用英文双引号（" "）包裹起来。例如：

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


入参

grantType String  REQUIRED

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

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

customerBelongsTo String  REQUIRED

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

更多信息：

  • 最大长度：64 字符

authCode String  

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

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

更多信息：

  • 最大长度：128 字符

refreshToken String  

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

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

更多信息：

  • 最大长度：128 字符

merchantRegion String  

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

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

更多信息：

  • 最大长度：2 字符

merchantAccountId String  

用于标识商户账号的专属 ID。

当您使用一个客户端 ID 在多地展业时，请指定此参数。

更多信息：

  • 最大长度：64 字符

出参

result Result  REQUIRED

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

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 可以是用户的电子邮件地址或电话号码，支付方式侧将以掩码方式返回，商户可据此识别已注册用户。

注意：当 result.resultCode 的值为 SUCCESS 且 consult 接口中 scopes 参数的值为 AGREEMENT_PAY 时，此字段将返回。

更多信息：

  • 最大长度：64 字符

extendInfo String  

扩展信息。

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

更多信息：

  • 最大长度：2048 字符
API Explorer

请求

URL

Method
POST
Case
json
{
  "merchantAccountId": "2188234232",
  "authCode": "663A8FA9D83648EE8AA11FF68298XXXX",
  "customerBelongsTo": "GCASH",
  "grantType": "AUTHORIZATION_CODE"
}

响应

Case
Case description
If you apply for the access token of Touch'n Go, the following response is returned:
json
{
  "accessToken": "281011030220200914TLsu9RhgUv87Lf1111****",
  "accessTokenExpiryTime": "2022-09-14T17:14:16+08:00",
  "extendInfo": "{\"userId\":\"100000111111****\",\"userLoginId\":\"6017271****\"}",
  "refreshToken": "281011111110200914aGT3jbpxci875H0041****",
  "refreshTokenExpiryTime": "2023-03-16T17:14:16+08:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  },
  "userLoginId": "6017271****"
}

结果处理逻辑

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

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

结果码

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

授权已完成。请存储 accessToken 和其他相关字段。

ACCESS_DENIEDF访问被拒绝。

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

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

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

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

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

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

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

INVALID_AUTHCODEF授权码无效。

重新发起授权，调用 consult 接口获取 authcode。如果授权码正确但仍有问题，请联系 Antom 技术支持进行排查。

INVALID_CLIENT_STATUSF客户端状态无效。

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

INVALID_REFRESH_TOKENF刷新令牌无效。

使用有效的 refreshToken 重新发起请求。如果刷新令牌正确但仍有问题，请联系 Antom 技术支持进行排查。

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

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

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

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

NO_INTERFACE_DEFF接口未定义。

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

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

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

OAUTH_FAILEDFOAuth 授权流程失败。

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

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

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

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

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

SYSTEM_ERRORF系统错误发生。

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

UNKNOWN_CLIENTF客户端未知。

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

USER_NOT_EXISTF用户在支付方式端不存在。

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

USER_STATUS_ABNORMALF用户在支付方式端的状态异常。

请联系 Antom 技术支持以了解具体原因。  

AUTH_IN_PROCESSU授权仍在处理中。

请持续调用此接口，直到收到最终结果状态。

REQUEST_TRAFFIC_EXCEED_LIMITU请求流量超过限制。

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

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

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