集成指南

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

集成前提

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

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

详情请参阅集成指南。

集成步骤

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

1. 从 Antom 获取并显示授权二维码。
2. 获取授权码。
3. 申请支付令牌。
4. 发起支付。
5. 获取支付结果。

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

1. 从 Antom 获取授权二维码

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

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

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

2. 呈现授权二维码

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

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

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

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

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

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

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

步骤 3：申请授权令牌

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

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

• grantType：传入固定值 AUTHORIZATION_CODE 。
• customerBelongsTo：指定您请求授权的目标支付方式。
• authCode：步骤 2 中获得的 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 的值。该字段的值已经经过隐私保护处理，可以直接进行展示。

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

步骤 4：发起支付

如果目标支付方式的余额足以支付买家的订单，您可以调用 支付（代扣） 接口来发起扣款。在请求中请正确传入以下参数：

• productCode：传入值为 AGREEMENT_PAYMENT。
• paymentMethod.paymentMethodId：您通过调用 申请支付令牌 接口获取到的支付令牌（accessToken）的值。
• paymentExpiryTime：如果您不指定此字段的值，则扫码签约请求过期时间为支付请求发送后的一分钟。如果您想限制支付请求的过期时间比一分钟更短，可以通过此字段传入对应的时长。值得注意的是，过期时间不支持比一分钟更长，另外，此字段的值需遵循 ISO 8601 标准。详情参考 支付（代扣）接口字段说明。
• paymentNotifyUrl：用于接收异步通知的地址，建议传入此参数。

在 支付（代扣） 接口的响应中，您需要根据 result.resultStatus 的值来判断扣款是否成功：

• 如果值为 S ，则扣款成功。
• 如果值为 U ，则交易仍在进行中。您需要通过轮询 支付结果查询 接口查询支付状态或等待异步通知来获取交易结果。
• 如果值为 F ，则扣款失败。您需要根据 resultCode 进行处理。

如果您无法收到响应，我们建议您使用相同的参数再次调用 支付（代扣）接口。

步骤 5：获取支付结果

由于网络问题，异步通知有无法触达或延迟的可能性。为了获得准确的支付结果，您必须同时集成异步通知和支付结果查询服务。

1. 接收异步通知

除去从重定向到支付结果页面获取支付结果外，您还可以通过 支付（代扣）接口中的 paymentNotifyUrl 参数来设置异步通知地址。当支付完成或支付超时后，Antom 会通过 支付通知 接口向该地址发送异步通知。

当您收到 Antom 的通知时，您必须按照处理通知的示例代码格式返回响应。如果您未向 Antom 返回响应，或由于网络问题响应未被 Antom 接收到，Antom 则会在 24 小时内自动重试发送异步通知，最多重试八次或直至收到正确的响应终止发送。发送间隔为：0 秒，2 分钟，10 分钟，10 分钟，1 小时，2 小时，6 小时和 15 小时。

注意：支付成功后， Antom 会立即向您发送支付成功的异步通知。支付失败时，Antom 会在支付订单关闭后向您发送支付失败的异步通知。默认关单时间通常为支付发起后的 14 分钟。

2. 查询支付状态

我们建议您通过调用 支付结果查询 接口来查询支付状态。您可以在发起支付请求后且订单未关闭前使用此接口。

在 支付结果查询 接口返回的响应中，务必依赖 paymentStatus 作为支付状态，建议您按照一下表格做后续引导：

有关支付状态的详细信息，请参阅支付状态描述。

最佳实践

为了获取准确的支付结果，建议您在数据库中维护一个订单表，至少包括两个字段：订单号和订单状态。并按照以下方式使用异步通知和支付结果查询服务：

• 异步通知：监听 Antom 的异步通知，并在接收到异步通知后返回响应。然后检查数据库中的订单状态：

• 如果订单状态为INIT，根据异步通知更新订单状态。
• 如果订单状态不是INIT，说明已经通过查询服务获取了最终支付结果，并更新了订单状态。不需要进一步操作。

• 支付查询：通过轮询的形式发起对支付结果的主动查询。在每次查询之前，您需要检查数据库中的订单状态：

• 如果订单状态为INIT，发起查询。如果获取到最终支付结果，更新数据库中的订单状态，否则继续轮询过程。
• 如果订单状态不是INIT，则表示已经进行了查询过程并获得了最终支付结果并用于更新订单状态，无需采取进一步操作。

图 1. 使用异步通知和支付结果查询的最佳实践