在发起扫码签约之前，您需要先获取买家的授权。授权成功后，您需要获取授权码以申请用于后续一键支付的支付令牌。当买家取消已签约扫码签约支付方式的授权时，您需要对支付令牌做相关处理。

集成前提

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

• 在 Antom Dashboard 上注册。
• 在 Antom Dashboard 上设置您的密钥。
• 配置一个接收异步通知的地址。

详情请参阅集成指南。

获取授权

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

1. 从 Antom 获取授权二维码。
2. 显示授权二维码。
3. 获取授权码。
4. 申请支付令牌。
5. （可选）刷新支付令牌。

步骤1：从 Antom 获取授权二维码

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

调用 授权咨询 接口时，请在请求中正确传入以下参数：

• authRedirectUrl：授权完成后，将买家重定向到他们移动客户端的商户页面的链接。扫码签约场景下买家完成授权后移动端不会被重定向至商户侧页面。
• authState：由您自行指定的字符串，用于标识授权请求。
• customerBelongsTo：指定您请求授权的目标支付方式。
• scopes：传入固定值为 AGREEEMENT_PAY 。
• terminalType：表示商户端所在的终端类型。值设置为 WEB 。

步骤2：呈现授权二维码

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

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

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

1. 配置接收授权结果通知的地址。详情请参阅通知。
2. 当买家同意授权后，您将收到由 Antom 发送给您的授权成功通知 。
3. 接收到异步通知后，请按照要求中的指示返回响应。否则 Antom 会重新发送异步通知。

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

• 授权成功：需要您在 Web 客户端处理重定向到授权结果页面。
• 授权失败：如果买家因授权超时或失败未能同意授权，建议您引导买家重新发起授权。通常，如果等待超过 15 分钟，您未收到签约授权通知，则可以判定本次授权失败。

由于授权链接只能使用一次，如果用户授权失败，您需要使用新的 authState 值来再次调用 授权咨询 接口。

步骤4：申请授权令牌

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

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

• grantType：传入固定值 AUTHORIZATION_CODE 。
• customerBelongsTo：指定您请求授权的目标支付方式。
• authCode：步骤3 中获得的 authCode 值。

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

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

在请求的响应中，您将收到以下关键参数：

• accessToken：支付令牌。

注意：

• 由于历史原因，以上关键参数适用于新商户。如果您已经是 Antom 商户，可以继续消费 accessTokenExpiryTime、refreshToken 和 refreshTokenExpiryTime 字段。请参阅下表了解更多令牌有效期信息。
• 如果调用接口后未收到响应，建议您使用相同的参数和参数值再次发起请求。
• 如果收到的响应中没有返回支付令牌（accessToken），建议您按如下方式处理：

• 如果result.resultStatus的值为 U，使用相同的参数和参数值重新发送请求。
• 如果result.resultStatus的值为 F，根据结果代码排查问题。如果需要再次调用接口获取支付令牌，由于 authCode 只能使用一次，您需要从步骤1开始获取新的授权码（authCode），然后调用 申请支付令牌 接口。

• 如果您需要在客户端展示买家用于扫码签约的关联账户，可以使用 申请支付令牌 接口响应返回的 userLoginId 的值。该字段的值已经经过隐私保护处理，可以直接进行展示。

关于扫码签约支持的支付方式，支付令牌有效期如下表所示：

取消授权

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

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

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

在接收到异步通知后，您可按照要求中的指示返回响应。否则 Antom 会重新发送异步通知。