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

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

集成前提

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

• 注册 Alipay 开发者中心账号。
• 设置您的密钥。
• 配置签约结果接收地址。配置方法请参考 接收通知。

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

获取代扣授权

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

1. 向Alipay咨询授权地址
2. 跳转买家至支付方式授权页面。建议您在支付方式授权页面上根据买家区域动态渲染支持的支付方式。
3. 获取授权码
4. 申请支付令牌
5. （可选）更新支付令牌

步骤一：向 Alipay 咨询授权地址

当您已经在合同中对想要支持的支付方式完成签约后，即可调用 咨询授权地址 接口。Alipay在接口响应中为您返回用于获取买家代扣授权的地址，该地址为以下参数的值：

• normalUrl
• schemeUrl
• applinkUrl

【注意】在一个授权流程中，代扣授权地址仅允许使用一次。即若以上三个 URL 都返回，仅允许使用三者其一。

各个支付方式对于以上三种参数的返回情况有所不同，即每个支付方式会返回以上三种参数中的部分或全部。

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

• authRedirectUrl: 授权完成后，用于买家重定向到商户页面的 URL 。这个 URL 将被用于拼接成步骤 3 中的重构 URL。
• authState: 由您自行指定的字符串，用于标识一次授权请求。该字符串将被用于拼接成步骤 3 中的重构 URL。
• customerBelongsTo: 指定您正在请求授权的目标支付方式。
• scopes: 固定值为 AGREEMENT_PAY。
• terminalType: 表示商户端所在的终端类型。

步骤二：跳转买家至支付方式授权页面

将买家从您的应用中跳转至支付方式授权页面。处理跳转的过程中，您需要根据买家所在应用的运行环境，分别选择适合的URL推进跳转流程：

• 如果买家所在应用处于电脑端浏览器内，您可以使用 normalUrl 推进跳转流程。
• 如果买家所在应用处于手机端浏览器内，建议您参考 跳转 URL 使用最佳实践进行配置。
• 如果买家所在应用处于手机端app内，建议您参考 跳转 URL 使用最佳实践进行配置。

买家在支付方式授权页面进行相关操作，可能会发生授权成功或授权失败的情况，这两种情况下的后续跳转如下：

• 授权成功：则一定会跳转回商户页面，页面地址为 authRediectUrl、authCode、authState 三个参数拼接而成的重构URL。
• 授权失败：

• 由于买家主动点击放弃授权等原因退出授权页面，部分支付方式支持买家回跳到商户页面。该商户页面地址为 authRediectUrl。
• 如果由于买家超时未授权或者授权失败，买家未能回跳到商户页面，则建议您引导买家重新发起授权。通常，如果等待超过 15 分钟，买家未能回跳至商户页面，则可以判定本次授权失败。

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

步骤三：获取授权码

买家授权成功后，您可以通过以下方式获取授权码（authCode）:

• 从支付方式返回的重构URL中获取
• 从Alipay发送给您的授权成功通知中获取

从重构URL中获取

买家授权成功后，会跳转到支付方式返回的重构URL，该URL由三部分组成：

• 您在 咨询授权地址 接口中传入的authRedirectUrl参数值
• 支付方式返回的authCode
• 您在 咨询授权地址 接口中传入的authState参数值

以下示例为一个重构URL：

https://www.alipay.com/?authCode=d2f60253-ecdc-e9bc-27d1- 566970191040&authState=663A8FA9-D836-48EE-8AA1-1FF682989DC7

您可以从重构 URL 中获取到 authCode 的值。但值得注意的是，在使用该 authCode 值之前，务必检查重构 URL 中的 authState 的值与您在 咨询授权地址 接口传入的 authState 参数值是一致的。如果不一致，则该重构 URL 不可信，跳转过程可能发生了被攻击等恶性事件，重构 URL 的 authCode 不可以被使用。

从授权通知中获取

由于网络不稳定等原因您可能会无法获取重构 URL, 因此 Alipay 为您提供了另一种获取授权码（authCode）的方式：从授权异步通知中获取。

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

【注意】您可以同时通过重构 URL 和授权通知两种方式获取 authCode，如获得多个 authCode，请使用最先抵达的 authCode，不要多次使用同一个authCode申请支付令牌。

步骤四：申请支付令牌

获取到授权码（authCode）后，调用 申请支付令牌 接口以获得支付令牌（accessToken）。为防止因支付令牌（accessToken）失效而导致交易失败，可以在支付令牌（accessToken）过期前再次调用 申请支付令牌 接口并使用refreshToken来获取新的支付令牌（accessToken）。

获取支付令牌

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

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

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

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

{
  "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）后再次调用 申请支付令牌 接口。

• 如果您需要在应用内为买家展示授权服务对应的绑定账号，您可以使用 applytoken 接口中会返回的userLoginId，该字段的返回值已脱敏，可直接进行展示。

更新支付令牌

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

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

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

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

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

注意：

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

支付令牌生命周期表

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

表 1. 支付方式令牌有效期

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

取消代扣授权

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

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

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

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