vaultPaymentMethod
在发起支付之前,请使用此接口绑定支付方式。通过接口响应,您可以获取 cardToken 或一个或多个 normalUrl、schemeUrl 或 applinkUrl。cardToken 可用于通过 pay(单笔支付)接口发起支付,而这些 URL 可用于让用户跳转以完成资产绑定过程。
结构
报文由报文头和报文体组成。本文主要介绍报文体结构信息,有关报文头的结构信息,请参阅:
注意:将每个参数(除数组外)的数据类型设置为字符串,即参数的值必须使用英文双引号(" ")包裹起来。例如:
- 如果参数的数据类型为整数属性,且其值为 20,设置为 "20"。
- 如果参数的数据类型为布尔属性,且其值为 true,设置为 "true"。
入参
vaultingRequestId String REQUIRED
由商户生成的用于标识绑卡请求的专属 ID。
更多信息:
- 此为幂等字段。对于使用相同 vaultingRequestId 发起的资产绑定请求,如果最终状态为S或F,请求应返回相同的结果。
- 最大长度:64 字符
vaultingNotificationUrl String REQUIRED
接收资产绑定结果通知的地址。
更多信息:
- 最大长度:2048 字符
redirectUrl String REQUIRED
绑卡完成后,买家跳转到的商户页面链接。
注意:如果希望在绑卡完成后买家直接跳转到您的页面,请指定此参数。
更多信息:
- 最大长度:2048 字符
merchantRegion String
商户经营业务的国家或地区。此参数的值基于 ISO 3166 国家代码标准的二位字母国家或地区代码。
可能的值包括 US, SG, HK, PK, JP, CN, BR, AU, 和 MY。
注意:在使用全球收单网关(GAGW)产品时指定此参数。
更多信息:
- 最大长度:2 字符
paymentMethodDetail PaymentMethodDetail REQUIRED
要绑定的支付方式的详细信息。
env Env REQUIRED
下单环境的信息,例如设备信息。
merchantAccountId String
用于标识商户账号的专属 ID。
当您使用一个客户端 ID 在多地展业时,请指定此参数。
更多信息:
- 最大长度:64 字符
metadata String
用于提交元数据,包括特殊用例信息。
当您需要添加元数据时指定此参数。
更多信息:
- 最大长度:2048 字符
出参
result Result REQUIRED
接口调用的结果。 如果此接口调用成功,支付方式绑定成功。
vaultingRequestId String REQUIRED
商户为绑卡请求而分配的专属 ID。
更多信息:
- 最大长度:64 字符
paymentMethodDetail PaymentMethodDetail
需要绑定的支付方式的详细信息。
注意:当 result.resultStatus 的值为 S 时,返回此参数。
normalUrl String
将用户跳转到默认浏览器或嵌入式 WebView 中的 WAP 或 WEB 页面的链接。
注意:
- 当 result.resultCode 的值为 VERIFICATION_IN_PROCESS 时,可能会返回以下一个或多个链接:schemeUrl、appLinkUrl 和 normalUrl。
- 当 paymentMethodType 的值为 CARD 时,用户需要通过此链接访问的页面完成 3DS 验证。
更多信息:
- 最大长度:2048 字符
schemeUrl String
应用安装完成后,用于将用户跳转到 Android 或 iOS 系统中打开应用的 URL scheme。
更多信息:
- 最大长度:2048 字符
applinkUrl String
应用安装完成后自动跳转,如果安装失败则跳转至 WAP 页面。
更多信息:
- 最大长度:2048 字符
API Explorer
请求
URL
Method
POST
{
"merchantAccountId": "2188234232",
"vaultingRequestId": "123456789206",
"vaultingNotificationUrl": "www.test.com",
"redirectUrl": "www.test.com",
"paymentMethodDetail": {
"paymentMethodType": "CARD",
"card": {
"cardNo": "4112273146798764",
"brand": "VISA",
"cardholderName": {
"firstName": "xu",
"middleName": "fang",
"lastName": "jie",
"fullName": "xufangjie"
},
"billingAddress": {
"region": "CN",
"address1": "gongzhuan Road",
"city": "hangzhou",
"state": "zhejiang",
"zipCode": "310000"
},
"cvv": "123",
"expiryYear": "26",
"expiryMonth": "08",
"businessRegistrationNo": "96",
"is3DSAuthentication": "true"
}
},
"env": {
"terminalType": "app"
}
}响应
{
"paymentMethodDetail": {
"card": {
"brand": "VISA",
"cardToken": "ALIPAY9CGwsAeMBug+G2dSKDV6AIsNKTxAFNkOMoj8Gxvt8h0eDUbd6nO5CwMFIjEFERWxCAo/b1OjVTvtl1zspyMGcg==",
"maskedCardNo": "************8764"
},
"paymentMethodType": "CARD"
},
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success.",
"resultStatus": "S"
},
"vaultingRequestId": "123487889889"
}结果处理逻辑
对于不同的请求结果,需要采取不同的行动。result.resultStatus 的可能响应包括:
- 结果代码不是 VERIFICATION_IN_PROCESS: 接口调用失败。使用新 vaultingRequestId 的值再次调用此接口。
- 结果代码是 VERIFICATION_IN_PROCESS: 检查以下三个 URL(appLinkUrl,normalUrl,schemeUrl)是否返回了一个或多个:
- 返回一个或多个链接: 绑卡创建成功。将用户跳转到提供的特定链接以完成绑卡。
- 没有返回链接: 绑卡创建失败。使用新的 vaultingRequestId 值再次调用此接口。如果问题持续存在,请联系 Antom 技术支持。
结果码
| 结果码 | 值 | 结果码信息 | 行动建议 |
|---|---|---|---|
| SUCCESS | S | 成功 | 资产绑定会话创建成功。无需进一步操作。 |
| PARAM_ILLEGAL | F | 缺少必需的参数,或者存在非法参数。例如,非数字输入、无效的日期,或者参数的长度和类型错误。 | 检查并验证当前接口所需的请求字段(包括头部字段和正文字段)是否正确传递并有效。 |
| PROCESS_FAIL | F | 发生了常见的业务失败。 | 获取 Antom 技术支持前请勿重试。 |
| UNKNOWN_EXCEPTION | U | 由于未知原因,接口调用失败。 | 再次调用接口以解决问题。如果问题未解决,请联系 Antom 技术支持。 |
| VERIFICATION_IN_PROCESS | U | 支付方式信息的验证正在进行中。 | 获取任一链接(appLinkUrl, normalUrl, schemeUrl)并打开该链接。如果没有返回链接,请使用新的请求 ID 再次调用此 接口。如果问题仍然存在,请联系 Antom 技术支持。 |
| VERIFICATION_FAIL | F | 支付方式信息的验证失败。 | 使用新的请求 ID 再次调用此接口。 |