用户授权

2024-06-03 09:58

在发起扫码签约之前，您需要先获取买家的授权。授权成功后，您需要获取授权码以申请用于后续一键支付的支付令牌，并在以下情况对支付令牌相应处理：

对于已授权用于扫码签约的支付方式，当该支付方式的支付令牌即将到期时，您需要对支付令牌进行更新。
当买家取消已签约扫码签约支付方式的授权时，您需要对支付令牌做相关处理。

集成前提

在正式开始集成之前，您需要完成以下准备工作：

在 Antom Dashboard 注册账号。
设置您的密钥。
配置签约结果接收地址。配置方法请参考接收通知。

欲知更多详情，请参考 Antom 的集成指南。

获取扫码签约授权

为获取买家对于扫码签约服务的授权，您需要完成以下集成步骤：

向 Antom 咨询授权二维码
呈现授权二维码
从授权通知中获取授权码
申请支付令牌
（可选）更新支付令牌

步骤一：向 Antom 咨询授权二维码

当您已经在合同中对想要支持的支付方式完成签约后，即可调用 咨询授权地址 接口。Antom 在接口响应中为您返回用于买家扫码签约的二维码，该二维码值为 authCodeForm.codeDetails.codeValue 参数的值，该值提供文本和图片两种格式，您可以根据需要选择使用。

调用 咨询授权地址 接口时，在请求中注意传入以下参数：

authRedirectUrl: 签约完成后的移动端商户侧回跳地址。扫码签约场景下买家完成授权后移动端不会回跳至商户侧页面。
authState: 由您自行指定的字符串，用于标识一次授权请求。该字符串将被用于拼接成步骤 3 中的重构 URL。
customerBelongsTo: 指定您正在请求授权的目标支付方式。
scopes: 固定值为 AGREEMENT_PAY。
terminalType: 表示商户端所在的终端类型。固定值为 WEB。

步骤二：呈现授权二维码

获取到 Antom 返回的签约二维码值后，当您选择使用文本码值时，需要您自行生成二维码图片在您的 PC 前端页面渲染，当您选择使用图片码值时，您可直接在您的 PC 前端页面渲染该图片，买家通过扫描二维码进行签约授权。

步骤三：从授权通知获取授权码

买家授权成功后，您可以从 Antom 发送给您的授权成功通知中获取授权码（authCode）:

配置授权结果异步通知接收地址。配置方法请参考接收通知。
买家同意扫码签约授权后，您会接收到 Antom 发送给您的授权成功通知。
接收到异步通知后，请按照通知处理要求进行回应，否则 Antom 会重发异步通知。

买家在签约过程中可能会发生授权成功或授权失败的情况，这两种情况下的后续跳转如下：

授权成功：需要您在 PC 侧处理跳转到您提供的签约结果页。
授权失败：

如果由于买家超时未授权或者授权失败，则建议您引导买家重新发起授权。通常，如果等待超过 15 分钟，您未收到签约授权通知，则可以判定本次授权失败。

由于二维码值仅能使用一次，如果买家授权失败，您需要使用新的 authState 值再次调用 咨询授权地址 接口。

步骤四：申请支付令牌

获取到授权码（authCode）后，调用 申请支付令牌 接口以获得支付令牌（accessToken）。

获取支付令牌

务必在取得授权码（authCode）后的一分钟内调用 申请支付令牌 接口进行支付令牌（accessToken）的申请，否则授权码（authCode）将过期并失效。只有获得了支付令牌（accessToken），后续才能实现从买家账户自动扣款。

调用 申请支付令牌 接口时，在请求中注意传入以下参数：

grantType：值为 AUTHORIZATION_CODE 。
customerBelongsTo：用于扫码签约的支付方式对应值。
authCode：步骤 3 中获得的 authCode 值。

以下示例是申请支付令牌的请求样例：

copy
{
  "grantType": "AUTHORIZATION_CODE",
  "customerBelongsTo": "GCASH",
  "authCode": "d2f60253-ecdc-e9bc-27d1-566970191040"
}

在请求的响应中，您会获得以下关键参数：

accessToken: 即支付令牌
accessTokenExpiryTime：支付令牌的过期时间
refreshToken：用于更新当前支付令牌时需要用到的更新令牌
refreshTokenExpiryTime：上述更新令牌的过期时间。通常 refreshTokenExpiryTime 的值比 accessTokenExpiryTime 的值更大，以确保支付方式可用。更新令牌过期后，需要从步骤 1 重新开始，获取新的授权码（authCode）后再次调用 申请支付令牌 接口。

注意：
如果调用接口后未收到响应，建议您使用同样的参数及参数值再次发起请求。
如果调用接口后能够收到响应，但响应中未返回支付令牌（accessToken），建议处理方式如下：
如果 result.resultStatus 值为 U，使用同样的参数及参数值再次发起请求
如果 result.resultStatus 值为 F，根据 result.resultCode 的提示对相关问题进行修复。如需再次调用接口获取支付令牌，由于 authCode 只能使用一次，调用 申请支付令牌 接口失败后，则需要从步骤 1 重新开始，获取新的授权码（authCode）后再次调用 申请支付令牌 接口。
如果您需要在应用内为买家展示授权服务对应的绑定账号，您可以使用 申请支付令牌 接口中会返回的 userLoginId，该字段的返回值已脱敏，可直接进行展示。

更新支付令牌

一旦支付令牌（accessToken）过期则无法再被用于买家账户扣款，因此您需要在支付令牌（accessToken）即将过期前，调用 申请支付令牌 接口对支付令牌（accessToken）进行更新。此时，在请求中注意传入以下参数：

grantType：值为 REFRESH_TOKEN 。
customerBelongsTo：用于扫码签约的支付方式对应值。
refreshToken：在之前的步骤中，以获取支付令牌为目的调用 申请支付令牌 接口过程中获得的更新令牌参数（refreshToken）值。

以下示例是更新支付令牌的请求样例：

copy
{
  "grantType": "REFRESH_TOKEN",
  "customerBelongsTo": "GCASH",
  "refreshToken": "281xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7811"
}

务必使用最新的 refreshToken 来延长 accessToken 的有效期。由于部分支付方式可能会在您再次调用 申请支付令牌 接口以更新令牌时（即调用 申请支付令牌 接口时指定 grantType 的值为 REFRESH_TOKEN），会给您返回新的 refreshToken 值。

注意：
建议您至少在支付令牌（accessToken）到期前十天前对支付令牌进行更新，以便 Antom 技术支持团队有足够的时间进行相关处理。对于支付令牌（accessToken）具有较长有效期的支付方式，例如 Kakao Pay，此规则同样适用。
支付令牌（accessToken）具有较长有效期的支付方式，例如Kakao Pay，可能存在不提供 refreshToken 和 refreshTokenExpiryTime 参数的情况。

支付令牌生命周期表

因各国风控要求不同，支付方式令牌有效期不同，最低有效期为一年。

建议您自行维护一张包含所有支付方式的支付令牌（accessToken）信息的生命周期表，以便定期检索即将过期的支付令牌（accessToken）并完成更新。例如：

取消扫码签约授权

在授权完成后，买家可在商户侧或支付方式侧取消授权，您需要针对这两种情况执行不同的操作：

如果买家在您的应用内取消授权，您需要通过 授权取消 接口使支付方式的支付令牌失效。在接口请求中传入该扫码签约服务对应的支付令牌（accessToken），接口调用成功后可使得该支付令牌（accessToken）失效。
如果买家在支付方式侧取消授权，您会接收到授权取消通知。欲接收取消授权异步通知，您需要提前配置接收授权取消通知的地址。当支付方式应用内发生授权取消时，通知中会指明被成功取消的扫码签约服务对应的支付令牌（accessToken）信息。以下示例展示了一个授权取消的异步通知：

copy
{
  "authorizationNotifyType": "TOKEN_CANCELED",
  "accessToken": "28100103_20215703001538122119",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  }
}

收到通知后，您可参考接收通知作为后续步骤指引，否则 Antom 会重发异步通知。