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

绑定支付方式

POST /v1/vaults/vaultPaymentMethod

在发起支付前使用此接口绑定支付方式。从接口响应中,您可以获取 cardToken 或者 normalUrl, schemeUrl, 或 applinkUrl 中的一个或多个。支付(收银台)接口可以用 cardToken 发起支付,而上述链接可用于重定向用户完成资产绑定过程。 

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息,有关报文头的结构信息,请参阅:


注意:将每个字段(除数组外)的数据类型设置为字符串。这意味字段值必须使用双引号(" ")括起来。例如:

  • 如果字段的数据类型为整数属性,且其值为 20,设置为 "20"。
  • 如果字段的数据类型为布尔属性,且其值为 true,设置为 "true"。

入参

vaultingRequestId String  REQUIRED

商户为绑卡请求而分配的专属 ID。 

更多信息:

  • 此为幂等字段。对于使用相同 vaultingRequestId 发起的资产绑定请求,如果最终状态为SF,请求应返回相同的结果。
  • 最大长度:64 字符

vaultingNotificationUrl String  REQUIRED

接收资产绑定结果通知的链接。 

更多信息:

  • 最大长度:2048 字符

redirectUrl String  REQUIRED

完成资产绑定后,买家被重定向到的商户页面链接。 

注意:如果希望在绑卡完成后直接将买家重定向到您的页面,请指定此参数。

更多信息:

  • 最大长度:2048 字符

merchantRegion String  

商户经营业务的国家或地区。此参数的值基于 ISO 3166 国家代码标准的二位字母国家或地区代码。 

可能的值包括 US, SG, HK, PK, JP, CN, BR, AUMY 

注意:使用全球收单网关(GAGW)产品时指定此参数。

更多信息:

  • 最大长度:2 字符

paymentMethodDetail PaymentMethodDetail  REQUIRED

被绑定支付方式的详细信息。 

Show child parameters

env Env  REQUIRED

下单环境的信息,例如设备信息。 

Show child parameters

出参

result Result  REQUIRED

接口调用的结果。 

Show child parameters

vaultingRequestId String  REQUIRED

商户为绑卡请求而分配的专属 ID。 

更多信息:

  • 最大长度:64 字符

paymentMethodDetail PaymentMethodDetail  

需要绑定的支付方式的详细信息。

result.resultStatus 的值为S时,返回此参数。

Show child parameters

normalUrl String  

将用户重定向到默认浏览器或嵌入式 WebView 中的 WAP 或 WEB 页面的链接。

result.resultCode 的值为VERIFICATION_IN_PROCESS时,可能会返回以下一个或多个链接:schemeUrlappLinkUrl normalUrl

paymentMethodType 的值为CARD时,用户需要通过此链接访问的页面完成 3DS 验证。

更多信息:

  • 最大长度:2048 字符

schemeUrl String  

应用安装完成后,用于将用户重定向到 Android 或 iOS 系统中打开应用的 URL scheme。

更多信息:

  • 最大长度:2048 字符

applinkUrl String  

应用安装完成后自动跳转,如果安装失败则跳转至 WAP 页面。

更多信息:

  • 最大长度:2048 字符
API Explorer
示例代码沙箱运行

请求

URL
请求体

响应

响应体

结果处理逻辑

对于不同的请求结果,需要采取不同的行动。result.resultStatus 的可能响应包括:

  • S: 表示接口调用成功。从该接口的响应中获取 cardToken。然后在发起支付时,在 支付(收银台)接口中使用 cardToken 的值。
  • F: 表示接口调用失败。有关失败原因的更多信息,请参阅 result.resultCode
  • U: 当返回此值时,根据 resultCode 的值是否为VERIFICATION_IN_PROCESS执行:
    • 结果代码不是VERIFICATION_IN_PROCESS: 接口调用失败。使用新 vaultingRequestId 的值再次调用此接口。
    • 结果代码是VERIFICATION_IN_PROCESS: 检查以下三个链接(appLinkUrlnormalUrlschemeUrl)是否返回了一个或多个:
      • 返回了一个或多个链接: 绑卡创建成功。将用户重定向到提供的特定链接以完成绑卡。
      • 没有返回链接: 绑卡创建失败。使用新的 vaultingRequestId 值再次调用此接口。如果问题持续存在,请联系 Antom 技术支持。

    结果码

    结果码结果码信息行动建议
    SUCCESSS成功

    资产绑定会话创建成功。无需进一步操作。

    PARAM_ILLEGALF缺少必需的参数,或者存在非法参数。例如,非数字输入、无效的日期,或者参数的长度和类型错误。

    检查并验证当前接口所需的请求字段(包括头部字段和正文字段)是否正确传递并有效。

    PROCESS_FAILF发生了常见的业务失败。

    获取 Antom 技术支持前请勿重试。

    UNKNOWN_EXCEPTIONU由于未知原因,接口调用失败。

    再次调用接口以解决问题。如果问题未解决,请联系 Antom 技术支持。

    VERIFICATION_IN_PROCESSU支付方式信息的验证正在进行中。

    获取任一链接(appLinkUrl, normalUrl, schemeUrl)并打开该链接。如果没有返回链接,请使用新的请求 ID 再次调用此 接口。如果问题仍然存在,请联系 Antom 技术支持。 

    VERIFICATION_FAILF支付方式信息的验证失败。

    使用新的请求 ID 再次调用此接口。