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 可用于通过 支付（收银台）接口发起支付，而这些 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

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

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 时，可能会返回以下一个或多个链接：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: 检查以下三个 URL（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 再次调用此接口。