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 发起的资产绑定请求，如果最终状态为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 object REQUIRED

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

Show child parameters

env Env object REQUIRED

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

Show child parameters

出参

result Result object REQUIRED

接口调用的结果。 

Show child parameters

vaultingRequestId String  REQUIRED

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

更多信息：

  • 最大长度：64 字符

paymentMethodDetail PaymentMethodDetail object 

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

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

Show child parameters

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

请求体

响应

响应体

结果处理逻辑

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

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

    结果码

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

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

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

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

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

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

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

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

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

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

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

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