Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

绑卡

本文指导您完成独立的绑卡接口集成，以允许买家在支付过程的任何阶段绑定银行卡。您可以收集买家的银行卡信息并存储在 Antom 中。在后续交易中，您可以使用 token 参数来发起支付，而无需再次收集买家的卡信息。

绑卡流程

下图展示了绑卡的集成步骤：

绑卡API-中文.png

集成步骤

按照以下步骤，使买家能够在支付过程的任何阶段绑定银行卡：

  1. 发起绑卡请求
  2. 获取绑卡结果

步骤 1：发起绑卡请求

Antom 提供了多种编程语言的服务器端 接口 库。以下代码以 Java 为例。要在 Java 中使用 Antom 接口，请确保您的系统安装了 Java 6 或更高版本。

安装接口库

您可以在 GitHub 上找到最新版本。

copy
<dependency>
  <groupId>com.alipay.global.sdk</groupId>
  <artifactId>global-open-sdk-java</artifactId>
  <version>2.0.21</version>
</dependency>

初始化请求实例

copy
String merchantPrivateKey = "YOUR PRIVATE KEY";
String alipayPublicKey = "ALIPAY PUBLIC KEY"
AlipayClient defaultAlipayClient = new DefaultAlipayClient(EndPointConstants.SG,
                merchantPrivateKey, alipayPublicKey);

创建绑卡请求

在请求中指定以下参数：

参数名称

是否必需?

描述

paymentMethodDetail.card

是

传入需要绑定的银行卡信息

vaultingRequestId

是

由商户生成的专属 ID。每次发起绑卡操作时，必须有新的 ID。

paymentMethodDetail.paymentMethod

是

该字段设置为 CARD。

redirectUrl

是

商户端绑定的结果页面，根据服务器端的结果来显示。

vaultingNotificationUrl

否

绑卡结果通知地址，可通过接口指定或在门户上设置固定值。

env

是

买家发起绑卡请求的环境。

有关所有参数的更多信息，请参阅 资产绑定会话创建 接口。

以下示例代码展示了如何发起支付：

copy
      AlipayPayRequest alipayPayRequest = new AlipayPayRequest();
        alipayPayRequest.setClientId(CLIENT_ID);
        alipayPayRequest.setPath("/ams/api/v1/vaults/vaultPaymentMethod");

        // replace to your vaultingRequestId
        String vaultingRequestId = UUID.randomUUID().toString();
        alipayPayRequest.setPaymentRequestId(paymentRequestId);

常见问题

问：如何设置 terminalType 的值？

答： 如果买家从 PC 发起请求， terminalType 需要设置为 WEB。

问：如何设置绑卡结果通知地址？

答：绑卡结果将通过 资产绑定通知 接口通知您。接收通知的地址可以通过 资产绑定会话创建 接口中 vaultingNotifyUrl 参数传入。

问：如何处理双标卡？

答：如果买家输入的是一张双标卡，您需要通过 paymentMethodDetail.card.selectedCardBrand 指定要绑定的银行卡品牌，后续的 token 支付将从该卡品牌扣款。

注意：对于欧洲的双标卡，需要让买家有权选择要绑定的银行卡品牌。

步骤 2：获取绑卡结果

当买家完成绑卡或绑卡超时，Antom 会通过服务器端交互将相应的绑卡结果发送给商户，您可以通过以下方法之一获取绑卡结果：

  • 接收异步通知
  • 主动查询结果

以下是通知请求的示例代码：

copy
{
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMsg": "success"
  },
  "acquirerInfo": {
    "acquirerName": "ADYEN",
    "acquirerTransactionId": "******",
    "referenceRequestId": "********"
  },
  "paymentMethodDetail": {
    "card": {
      "avsResultRaw": "4",
      "billingAddress": {
        "address1": "address1",
        "address2": "address2",
        "city": "Madrid",
        "region": "ES",
        "state": "Madrid",
        "zipCode": "280**"
      },
      "brand": "VISA",
      "cardToken": "******",
      "cvvResultRaw": "1",
      "expiredMonth": "02",
      "expiredYear": "27",
      "funding": "DEBIT",
      "issuingCountry": "BR",
      "lastFour": "0000",
      "bin": "409280",
      "issuerName": "BANCO ITAUCARD, S.A."
    },
    "paymentMethodType": "CARD"
  },
  "vaultingCreateTime": "2023-10-16T01:07:22-07:00",
  "vaultingRequestId": "requestId1697443641665"
}

如何验证通知的签名并作出响应，请参阅签名与验签。

常见问题

问： 何时会发送通知？

答：这取决于绑卡是否完成：

  • 如果绑卡成功完成，Antom 通常会在 3 到 5 秒内发送异步通知。对于某些支付方式，如柜台支付（OTC），通知可能会稍有延迟。

问：异步通知会被重新发送吗？

答：是的，以下情况异步通知将在 24 小时内自动重新发送：

  • 如果由于网络原因您没有收到异步通知。
  • 如果您收到来自 Antom 的异步通知 ，但是您没有按照处理通知的示例代码格式对通知做出响应。

通知最多可以重发 8 次，或者直到收到正确的响应以终止发送。发送间隔如下：0 分钟，2 分钟，10 分钟，10 分钟，1 小时，2 小时，6 小时，15 小时。

问：在响应异步通知时，我需要添加数字签名吗？答：如果您收到来自 Antom 的异步通知，您需要按照处理通知的示例代码格式返回响应，但您不需要在响应中添加数字签名。

 

问：我在通知中需要使用哪些关键参数？ 答：请注意以下关键参数：
  • result: 订单的绑定结果。
  • paymentMethodDetail：绑定密钥信息，如 cardToke。

主动查询结果

商户可以调用 绑定结果查询 接口 来发起对订单结果的查询。

参数名称

是否必需

描述

vaultingRequestId

✅

商户生成的绑定请求 ID。

以下示例代码展示了如何调用 绑定结果查询 接口:

copy
AlipayClient defaultAlipayClient = new DefaultAlipayClient(EndPointConstants.SG,
        merchantPrivateKey, alipayPublicKey);

AlipayPayQueryRequest alipayPayQueryRequest = new AlipayPayQueryRequest();
alipayPayQueryRequest.setClientId(CLIENT_ID);
alipayPayQueryRequest.setPath("/ams/api/v1/payments/inquiryPayment");

AlipayPayQueryResponse alipayPayQueryResponse;
try {
    alipayPayQueryResponse = defaultAlipayClient.execute(alipayPayQueryRequest);
} catch (AlipayApiException e) {
    String errorMsg = e.getMessage();
    // handle error condition
}

以下代码展示了请求报文的示例：

copy
{
  "vaultingRequestId": "123456789206"
}

以下代码展示了响应报文的示例：

copy
{
  "paymentMethodDetail": {
    "card": {
      "brand": "VISA",
      "cardToken": "ALIPAY9CGwsAeMBug+G2dSKDV6AIsNKTxAFNkOMoj8Gxvt8h0eDUbd6nO5CwMFIjEFERWxCAo/b1OjVTvtl1zspyMGcg==",
      "maskedCardNo": "************8764"
    },
    "paymentMethodType": "CARD"
  },
  "vaultingRequestId": "123487889889",
  "vaultingStatus": "SUCCESS",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

常见问题

问：我应该多久调用一次绑定结果查询接口？

答：推荐以轮询的形式发起查询，间隔 2s 直到查询到最终的绑卡结果或收到绑卡结果异步通知为止。

问：我在通知中需要使用哪些关键参数？

答：请注意以下关键参数：

  • result：仅代表本次接口调用的结果，对于订单的结果需要根据 vaultingStatus 进行判断：
    • SUCCESS 和 FAIL 表示最终结果。
    • PROCESSING 表示处理中。