绑卡
本文指导您完成独立的绑卡接口集成，以允许买家在支付过程的任何阶段绑定银行卡。您可以收集买家的银行卡信息并存储在 Antom 中。在后续交易中，您可以使用 token 参数来发起支付，而无需再次收集买家的卡信息。
绑卡流程
下图展示了绑卡的集成步骤：
集成步骤
按照以下步骤，使买家能够在支付过程的任何阶段绑定银行卡：
- 发起绑卡请求
- 获取绑卡结果
步骤 1：发起绑卡请求
Antom 提供了多种编程语言的服务器端 接口 库。以下代码以 Java 为例。要在 Java 中使用 Antom 接口，请确保您的系统安装了 Java 6 或更高版本。
安装接口库
您可以在 GitHub 上找到最新版本。
<dependency>
<groupId>com.alipay.global.sdk</groupId>
<artifactId>global-open-sdk-java</artifactId>
<version>2.0.44</version>
</dependency>初始化请求实例
import com.alipay.global.api.AlipayClient;
import com.alipay.global.api.DefaultAlipayClient;
import com.alipay.global.api.model.constants.EndPointConstants;
public class Sample {
public static final String CLIENT_ID = "";
public static final String ANTOM_PUBLIC_KEY = "";
public static final String MERCHANT_PRIVATE_KEY = "";
private final static AlipayClient CLIENT = new DefaultAlipayClient(
EndPointConstants.SG, MERCHANT_PRIVATE_KEY, ANTOM_PUBLIC_KEY, CLIENT_ID);
}
创建绑卡请求
在请求中指定以下参数：
参数名称 | 是否必需 | 描述 |
paymentMethodDetail.card | 是 | 传入需要绑定的银行卡信息。 |
vaultingRequestId | 是 | 由商户生成的专属 ID。每次发起绑卡操作时，必须有新的 ID。 |
paymentMethodDetail.paymentMethod | 是 | 该字段设置为 |
redirectUrl | 是 | 商户端绑定的结果页面，根据服务器端的结果来显示。 |
vaultingNotificationUrl | 否 | 绑卡结果通知地址，可通过接口指定或在门户上设置固定值。 |
env | 是 | 买家发起绑卡请求的环境。 |
有关所有参数的更多信息，请参阅 绑定支付方式 接口。
以下示例代码展示了如何发起支付：
public static void vaultPaymentMethod(){
AlipayVaultingPaymentMethodRequest alipayVaultingPaymentMethodRequest = new AlipayVaultingPaymentMethodRequest();
// set card info
CardPaymentMethodDetail cardPaymentMethodDetail = CardPaymentMethodDetail.builder().cardNo("4054695723100768").expiryMonth("01").expiryYear("2030").build();
PaymentMethodDetail paymentMethodDetail = PaymentMethodDetail.builder().paymentMethodType("CARD").card(cardPaymentMethodDetail).build();
alipayVaultingPaymentMethodRequest.setPaymentMethodDetail(paymentMethodDetail);
// set env
Env env = Env.builder().terminalType(TerminalType.WEB).build();
alipayVaultingPaymentMethodRequest.setEnv(env);
// replace with your vaultingRequestId
String vaultingRequestId = UUID.randomUUID().toString();
alipayVaultingPaymentMethodRequest.setVaultingRequestId(vaultingRequestId);
// replace with your notificationUrl
alipayVaultingPaymentMethodRequest.setVaultingNotificationUrl("https://www.yourNotifyUrl.com");
// replace with your redirectUrl
alipayVaultingPaymentMethodRequest.setRedirectUrl("https://www.yourMerchantWeb.com");
// do vaulting
AlipayVaultingPaymentMethodResponse alipayVaultingPaymentMethodResponse;
try{
alipayVaultingPaymentMethodResponse = CLIENT.execute(alipayVaultingPaymentMethodRequest);
}catch (AlipayApiException e){
String errorMsg = e.getMessage();
}
}常见问题
问：如何设置 terminalType 的值？
答： 如果买家从 PC 发起请求， terminalType 需要设置为
WEB。
问：如何设置绑卡结果通知地址？
答：绑卡结果将通过 资产绑定通知 接口通知您。接收通知的地址可以通过 资产绑定会话创建 接口中 vaultingNotifyUrl 参数传入。
问：如何处理双标卡？
答：如果买家输入的是一张双标卡，您需要通过 paymentMethodDetail.card.selectedCardBrand 指定要绑定的银行卡品牌，后续的 token 支付将从该卡品牌扣款。
注意：对于欧洲的双标卡，需要让买家有权选择要绑定的银行卡品牌。
步骤 2：获取绑卡结果
当买家完成绑卡或绑卡超时，Antom 会通过服务器端交互将相应的绑卡结果发送给商户，您可以通过以下方法之一获取绑卡结果：
- 接收异步通知
- 主动查询结果
接收异步通知
商户需要在服务器端实现 资产绑定通知 接口以接收来自 Antom 的绑卡通知。当绑卡完成或绑卡失败时，Antom 将通过此 URL 发送异步通知。
以下是通知请求的示例代码：
{
"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 秒内发送异步通知。对于某些支付方式，如现金支付，通知可能会稍有延迟。
问：异步通知会被重新发送吗？
答：是的，以下情况异步通知将在 24 小时内自动重新发送：
- 如果由于网络原因您没有收到异步通知。
- 如果您收到来自 Antom 的异步通知 ，但是您没有按照处理通知的示例代码格式对通知做出响应。
通知最多可以重发 8 次，或者直到收到正确的响应以终止发送。发送间隔如下：0 分钟，2 分钟，10 分钟，10 分钟，1 小时，2 小时，6 小时，15 小时。
问：在响应异步通知时，我需要添加数字签名吗？
答：如果您收到来自 Antom 的异步通知，您需要按照处理通知的示例代码格式返回响应，但您不需要在响应中添加数字签名。
问：我在通知中需要使用哪些关键参数？
答：请注意以下关键参数：
- result: 订单的绑定结果。
- paymentMethodDetail：绑定密钥信息，如
cardToken。
主动查询结果
商户可以调用 绑定结果查询 接口来发起对订单结果的查询。
参数名称 | 是否必需 | 描述 |
vaultingRequestId | 是 | 商户生成的绑定请求 ID。 |
以下示例代码展示了如何调用 绑定结果查询 接口:
public static void inquireVaulting(){
AlipayVaultingQueryRequest alipayVaultingQueryRequest = new AlipayVaultingQueryRequest();
//replace with your vaultingRequestId
alipayVaultingQueryRequest.setVaultingRequestId("c7f3ee64-c472-4d12-b8de-3157804ed55f");
AlipayVaultingQueryResponse alipayVaultingQueryResponse;
try{
alipayVaultingQueryResponse = CLIENT.execute(alipayVaultingQueryRequest);
}catch (AlipayApiException e){
String errorMsg = e.getMessage();
// handle error condition
}
}以下代码展示了请求报文的示例：
{
"vaultingRequestId": "c7f3ee64-c472-4d12-b8de-3157804ed55f"
}以下代码展示了响应报文的示例：
{
"paymentMethodDetail": {
"card": {
"brand": "VISA",
"cardToken": "ALIPAYRW7VmurJIvO5kUUqLgvyKJ+Q+4nhbQtaL0qVpHiwPidWDBiJal0weJJv5BSaPYsLyWCloE4MwfmN48sP1+xxxxx",
"maskedCardNo": "************0768"
},
"paymentMethodType": "CARD"
},
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success.",
"resultStatus": "S"
},
"vaultingRequestId": "c7f3ee64-c472-4d12-b8de-3157804ed55f",
"vaultingStatus": "SUCCESS"
}常见问题
问：我应该多久调用一次绑定结果查询接口？
答：推荐以轮询的形式发起查询，间隔 2s 直到查询到最终的绑卡结果或收到绑卡结果异步通知为止。
问：我在通知中需要使用哪些关键参数？
答：请注意以下关键参数：
- result：仅代表本次接口调用的结果，对于订单的结果需要根据 vaultingStatus 进行判断：
SUCCESS和FAIL表示最终结果。PROCESSING表示处理中。