集成指南

令牌支付产品可为您的网站或应用构建线上自动扣款功能，买家在首次支付时完成签约授权后，后续支付仅需一次点击即可完成或由您的后台直接扣款。其适用于以下场景：
  • 周期性支付：如订阅与会员服务，由您自己管理扣款周期。
  • 小额高频支付、复购率高的场景：如游戏和电商，可为买家提供快捷流畅的支付流程。
令牌支付产品支持在不同终端类型（Web/WAP/App）上部署，并且您只需要一次集成，就可以接入多种支付方式，如电子钱包、银行转账等。
Web/WAP
iOS
Android

步骤 4：申请支付令牌
服务端

在收到授权码（authCode）后一分钟内，调用 applyToken 接口来申请支付令牌（accessToken）。否则，授权码（authCode）将过期并失效。只有获得 accessToken 后，后续才能从买家账户自动代扣款。
调用 applyToken 接口时，在请求中正确传入以下参数：
以下是调用 applyToken 的代码示例：
public static void applyToken() {
  String authCode = "yourAuthCode";
  AlipayAuthApplyTokenRequest alipayPayRequest = new AlipayAuthApplyTokenRequest();

  // 设置 grantType
  alipayPayRequest.setGrantType(GrantType.AUTHORIZATION_CODE);
  // 设置请求授权的目标支付方式
  alipayPayRequest.setCustomerBelongsTo(CustomerBelongsTo.GCASH);
  // 设置 authCode
  alipayPayRequest.setAuthCode(authCode);

  // 申请支付令牌
  AlipayAuthApplyTokenResponse authApplyTokenResponse;
  try {
      authApplyTokenResponse = CLIENT.execute(alipayPayRequest);
  } catch (AlipayApiException e) {
      String errorMsg = e.getMessage();
      // 处理错误情况
  }
}
以下是申请支付令牌的请求报文示例：
{
"authCode": "663A8FA9D83648EE8AA11FF68298XXXX",
"customerBelongsTo": "GCASH",
"grantType": "AUTHORIZATION_CODE"
}
以下是申请支付令牌的响应报文示例：
{ 
"accessToken": "281011030220200914TLsu9RhgUv87Lf1111****",
"accessTokenExpiryTime": "2022-09-14T17:14:16+08:00",
"extendInfo": "{"userId":"100000111111****","userLoginId":"6017271****"}",
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "Success",
  "resultStatus": "S"
},
"userLoginId": "6017271****"
}
下表展示了申请支付令牌的响应报文中 result.resultStatus 字段可能返回的值，请您根据指引进行处理：
注意：如果您未收到响应报文，可能是网络超时所致。建议使用原请求参数重新调用接口。如果问题未解决，请联系 Antom 技术支持。
常见问题
问：authCode 可以多次调用吗？
答：不可以，authCode 只能使用一次。

问：authCode 的有效时间是多久？
答：通常为一分钟，建议您在一分钟内完成支付令牌的申请。

问：是否支持异步通知获取支付令牌？
答：不支持，仅能通过调用 applyToken 接口来申请支付令牌。

支付令牌有效期

关于令牌支付支持的支付方式，支付令牌有效期如下表所示：
注意：PayPay 首次签约完成后，有效期为 1 年。若在有效期内发生成功交易，则有效期将自该交易成功之日起自动顺延 1 年。

步骤 5：发起支付
服务端

买家授权成功后，您可以为买家提供代扣款服务，即买家在后续的购物中，每次付款都无需输入支付信息，系统自动完成订单对应金额的扣款。
发起令牌支付时，请指定以下参数：
以上参数是发起令牌支付的基本参数，完整参数和特定支付方式的额外要求请参考 pay（令牌支付）。
以下是调用 pay（令牌支付）接口的示例代码：
public static void pay() {
  AlipayPayRequest alipayPayRequest = new AlipayPayRequest();
  alipayPayRequest.setProductCode(ProductCodeType.AGREEMENT_PAYMENT);

  // 替换为您的 paymentRequestId
  String paymentRequestId = UUID.randomUUID().toString();
  alipayPayRequest.setPaymentRequestId(paymentRequestId);

  // 设置金额
  // 转换金额单位（实际金额应该在您的服务端计算）
  Amount amount = Amount.builder().currency("SGD").value("550000").build();
  alipayPayRequest.setPaymentAmount(amount);

  // 指定支付方式
  PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("GCASH").
  paymentMethodId("2828XXX77801726307481000Iba1Pm20IU171000179").build();
  alipayPayRequest.setPaymentMethod(paymentMethod);

  // 设置买家信息
  Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();

  // 替换为您的 orderId
  String orderId = UUID.randomUUID().toString();
  // 设置订单信息
  Order order = Order.builder().referenceOrderId(orderId).
  orderDescription("antom api testing order").orderAmount(amount).buyer(buyer).build();
  alipayPayRequest.setOrder(order);

  // 设置环境信息
  Env env = Env.builder().terminalType(TerminalType.WEB).clientIp("114.121.121.01").build();
  alipayPayRequest.setEnv(env);

  // 替换为您的通知地址
  alipayPayRequest.setPaymentNotifyUrl("http://www.yourNotifyUrl.com");

  AlipayPayResponse alipayPayResponse;
  try {
      alipayPayResponse = CLIENT.execute(alipayPayRequest);
  } catch (AlipayApiException e) {
      String errorMsg = e.getMessage();
      // 处理错误情况
  }
}
以下是请求报文的代码示例：
{
"env": {
  "clientIp": "114.121.121.01",
  "terminalType": "WEB"
},
"order": {
  "buyer": {
    "referenceBuyerId": "yourBuyerId"
  },
  "orderAmount": {
    "currency": "SGD",
    "value": "550000"
  },
  "orderDescription": "antom api testing order",
  "referenceOrderId": "f69cb774-8d47-4da9-bf91-08c656581cdf"
},
"paymentAmount": {
  "currency": "SGD",
  "value": "550000"
},
"paymentMethod": {
  "paymentMethodId": "2828XXX77801726307481000Iba1Pm20IU171000179",
  "paymentMethodType": "GCASH"
},
"paymentNotifyUrl": "http://www.yourNotifyUrl.com",
"paymentRequestId": "AGREEMENT_PAYMENT_REQUEST_2020070316170XXXX",
"productCode": "AGREEMENT_PAYMENT"
}
以下是响应报文的代码示例：
{
"paymentAmount": {
  "currency": "SGD",
  "value": "550000"
},
"paymentCreateTime": "2020-07-03T01:17:50-07:00",
"paymentId": "2020070311401080010018840027964XXXX",
"paymentRequestId": "AGREEMENT_PAYMENT_REQUEST_2020070316170XXXX",
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "Success",
  "resultStatus": "S"
}
}
下表展示了响应报文中 result.resultStatus 字段可能返回的值，请您根据指引进行处理：
注意：如果您未收到响应报文，可能是网络超时所致。建议使用原 paymentRequestId 重新调用接口。如果问题未解决，请联系 Antom 技术支持。
常见问题
问：如何设置 terminalType？
答：terminalType 的有效值如下：
  • 如果买家在 PC 浏览器发起交易，需要将 terminalType 指定为
    WEB
    。
  • 如果买家在移动浏览器上发起交易，需要将 terminalType 指定为
    WAP
    。添加 osType 参数，并根据买家的移动设备填写相应的系统参数
    ANDROID
    或
    IOS
    。

问：请求参数的值可以使用中文字符吗？
答：为了避免特定支付方式的不兼容情况，请勿在请求字段中使用中文字符。

问：如何设置接收支付通知的地址？
答：在 pay（令牌支付）接口中指定 paymentNotifyUrl 以接收支付结果（notifyPayment）的异步通知，或者在 Antom Dashboard 中配置接收地址。如果请求和 Antom Dashboard 都指定了地址，则请求中指定的值优先。

获取支付结果

您可以选择以下方法之一获取交易结果：
  • 接收来自 Antom 的异步通知
  • 主动查询支付结果
接收异步通知
查询支付结果

支付后操作

完成支付后，您可对交易进行以下支付后的操作：

取消交易

买家下单后您可以在一定期限内通过使用 cancel 接口主动关闭某笔交易，具体操作请参阅取消交易。

取消授权

买家完成授权后，您需在商户侧提供授权协议取消功能，原因如下：
  • 保障买家对其授权协议的自主管理权，允许买家根据个人账户安全策略或服务使用需求，随时终止已建立的授权关系。
  • 由于部分支付方式存在系统级限制，同一电子钱包账户在单一商户维度仅允许维持一个或者少量有效授权凭证。
提供取消授权功能需要进行的具体操作请参阅取消授权。

退款

不同支付方式的退款能力各有差异，若您需要了解 Antom 的退款规则及如何对成功的交易发起退款，请参阅退款。

对账

交易完成后，使用 Antom 提供的财务报告进行对账。有关如何对账和 Antom 结算规则的更多信息，请参阅对账。

最佳实践

Antom 为您提供签约二维码前置优化、客户端体验优化、支付结果展示、支付失败重试、接口超时时间设置等最佳实践方案，请参阅最佳实践了解详情。

支付方式特性

以下表格展示不同支付方式在完成授权后是否会返回买家的登录 ID（userLoginID），以及返回的 ID 格式示例：