inquireVaulting

2026-07-07 02:12

POST /v1/vaults/inquireVaulting

使用此接口查询支付方式的绑定状态。

结构

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

注意：将每个参数（除数组外）的数据类型设置为字符串，即参数的值必须使用英文双引号（" "）包裹起来。例如：
如果参数的数据类型为整数属性，且其值为 20，设置为 "20"。
如果参数的数据类型为布尔属性，且其值为 true，设置为 "true"。

入参

vaultingRequestId String REQUIRED

由商户生成的用于标识绑卡请求的专属 ID。

注意：此字段是幂等字段。对于使用相同 vaultingRequestId 值发起并达到最终状态S或F的资产绑定请求，应返回相同的结果。

更多信息：

最大长度：64 字符

merchantAccountId String

用于标识商户账号的专属 ID。

当您使用一个客户端 ID 在多地展业时，请指定此参数。

更多信息：

最大长度：64 字符

出参

result Result REQUIRED

请求调用结果的信息。

此字段不表示资产绑定结果。此字段仅表示该接口是否调用成功。

Show child parameters

vaultingRequestId String REQUIRED

由商户生成的用于标识绑卡请求的专属 ID。

更多信息：

最大长度：64 字符

normalUrl URL

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

注意：
当 result.resultStatus 的值为 S 且 vaultingStatus 的值为 PROCESSING 时，可能会返回以下一个或多个链接：schemeUrl、applinkUrl 和 normalUrl。
当 paymentMethodType 的值为 CARD 时，用户需要通过此链接访问的页面完成 3DS 验证。

更多信息：

最大长度：2048 字符

schemeUrl URL

应用安装完成后，用于在 Android 或 iOS 系统中打开应用的 URL scheme。

注意：当 result.resultStatus 的值为S且 vaultingStatus 的值为PROCESSING时，可能会返回以下一个或多个链接：schemeUrl、applinkUrl 和 normalUrl。

更多信息：

最大长度：2048 字符

applinkUrl URL

应用安装完成后，用于引导用户打开应用的链接，或者安装失败时，用于打开 WAP 页面的链接。对于 Android，该链接是 Native App Link。对于iOS，该链接是 Universal Link。

注意：当 result.resultStatus 的值为S且 vaultingStatus 的值为PROCESSING时，可能会返回以下一个或多个链接：schemeUrl、applinkUrl 和 normalUrl。

更多信息：

最大长度：2048 字符

paymentMethodDetail PaymentMethodDetail

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

注意：当 vaultingStatus 的值为 SUCCESS 时，返回此参数。

Show child parameters

vaultingStatus String

表示支付方式的绑定状态。有效值为：

SUCCESS: 表示绑定成功。
FAIL: 表示绑定失败。
PROCESSING: 表示绑定处理中。

注意：当 result.resultStatus 的值为 S 时返回此参数。

更多信息：

最大长度：10 字符

vaultingResultCode String

支付方式绑定操作的结果码。该参数的值取决于 vaultingStatus 参数的值：

当 vaultingStatus 为 SUCCESS 时，值为 SUCCESS。
当 vaultingStatus 为 PROCESSING 时，值为 VERIFICATION_IN_PROCESS。
当 vaultingStatus 为 FAIL 时，值为具体错误码，表示失败原因。详见绑卡结果码表格。

注意: 仅当 result.resultStatus 为 S 时返回此参数。

更多信息：

最大长度：64 字符

vaultingResultMessage String

vaultingResultCode 的可读描述信息。该参数的值取决于 vaultingStatus 参数的值：

当 vaultingStatus 为 SUCCESS 时，值为 success。
当 vaultingStatus 为 PROCESSING 时，值为 The verification is still under process。
当 vaultingStatus 为 FAIL 时，值为具体错误描述。详见绑卡结果码表格。

注意: 仅当 result.resultStatus 为 S 时返回此参数。

更多信息：

最大长度：256 字符

metadata String

您在绑定支付方式过程中提供的 metadata 信息。

当您在 vaultPaymentMethod 接口请求中指定了该参数时，系统会返回此参数。

更多信息：

最大长度：2048 字符

API Explorer

示例代码沙箱运行

请求

URL

Method

POST

请求体

响应

Case

Vaulting successful

Case description

The following response is returned for a successful vaulting:

响应体

结果处理逻辑

响应中 result.resultStatus 表示接口调用结果，vaultingStatus/vaultingResultCode/vaultingResultMessage 表示绑卡业务结果。请按以下另两个步骤处理响应：

第一步：检查接口调用结果 (result.resultStatus)

*result.resultStatus*	含义	后续操作
`S`	接口调用成功。	继续第二步，解读绑卡业务结果。
`F`	接口调用失败。	无需关注 vaultingStatus、vaultingResultCode、vaultingResultMessage（这些参数可能不存在）。请根据 result.resultCode 定位失败原因。
`U`	接口调用结果未知。	建议重新调用接口。如问题持续，请联系 Antom 技术支持。

注意: vaultingStatus、vaultingResultCode 和 vaultingResultMessage 仅在 result.resultStatus 为 S 时可靠。当 result.resultStatus 为 F 或 U 时，不可依赖这些参数的值。

第二步：解读绑卡业务结果

注意：仅当 result.resultStatus = S 时，此步骤才有效。

*vaultingStatus*	*vaultingResultCode*	含义	后续操作
`SUCCESS`	`SUCCESS`	绑卡成功	无需进一步操作。
`PROCESSING`	`VERIFICATION_IN_PROCESS`	绑卡处理中（如 3D Secure 验证进行中）	引导用户完成验证，之后再次调用本接口查询结果。
`FAIL`	（具体错误码）	绑卡失败	根据 vaultingResultCode 判断具体失败原因并采取对应操作。详见本页绑卡结果码列表。

接口调用结果码

注意：系统仅返回英文版结果码信息（resultMessage），表格中的中文文案仅供理解和参考，实际返回值以英文为准。

*resultCode*	*resultStatus*	*resultMessage*	处理建议
`SUCCESS`	`S`	成功。（Success.）	接口调用成功，无需进一步操作。
`CLIENT_FORBIDDEN_ACCESS_API`	`F`	客户端无权调用此接口。（The client is not authorized to use this API.）	检查客户端权限配置。
`INVALID_API`	`F`	接口无效或未激活。（The called API is invalid or not active.）	检查接口名称和版本。
`INVALID_CLIENT_STATUS`	`F`	客户端状态无效。（The client status is invalid.）	检查商户入驻状态。
`INVALID_SIGNATURE`	`F`	签名校验失败。请求的签名私钥与 Antom Dashboard 公钥不匹配。（The signature is not validated. The private key used to sign a request does not match the public key of Antom Dashboard.）	确认签名私钥与 Antom Dashboard 中配置的公钥匹配。
`KEY_NOT_FOUND`	`F`	未找到 Antom 或商户的私钥或公钥。（The private key or public key of Antom or the merchant is not found.）	检查 Antom 和商户的公私钥配置。
`MERCHANT_NOT_REGISTERED`	`F`	商户未注册。（The client status is invalid.）	请先完成商户入驻。
`NO_INTERFACE_DEF`	`F`	接口未定义。（API is not defined.）	检查接口路径是否正确。
`REQUEST_TRAFFIC_EXCEED_LIMIT`	`F`	请求流量超限。（The request traffic exceeds the limit.）	降低请求频率或联系 Antom 技术支持提升限额。
`VAULTING_NOT_EXIST`	`F`	资产绑定请求 ID 不存在。（The vaulting request ID does not exist.）	检查 vaultingRequestId 的值是否正确。若正确，请联系 Antom 技术支持获取具体原因。
`UNKNOWN_EXCEPTION`	`U`	由于未知原因，接口调用失败。（An API call has failed, which is caused by unknown reasons.）	重新调用接口以解决问题。若问题未解决，请联系 Antom 技术支持。

绑卡结果码

注意：系统仅返回英文版绑卡结果码信息（vaultingResultMessage），表格中的中文文案仅供理解和参考，实际返回值以英文为准。

*vaultingResultCode*	*vaultingResultMessage*	处理建议
`ACCESS_DENIED`	访问被拒绝。（Access denied.）	联系 Antom 技术支持并提供 vaultingRequestId 和 vaultingResultCode。
`ACCOUNT_CLOSED`	账户已关闭。请核实账户号码是否准确，并且不要再次使用相同的 PAN 或 Token 发起处理。（The account is closed. Please verify the account number for accuracy and do not attempt to process the same PAN or token again.）	联系 Antom 技术支持并提供 vaultingRequestId 和 vaultingResultCode。
`AUTHENTICATION_REQUIRED`	需要进行 3D Secure 认证。（3D Secure authentication is required.）	重新发起绑卡并引导用户完成 3D Secure 认证。
`BLOCKED_FIRST_USED`	卡片暂时被冻结、尚未激活，或因特殊状态无法处理，例如新持卡人尚未激活卡片。（When a card is either temporarily blocked, has not been activated for first use, or is subject to special conditions that prevent processing (e.g., new cardholder not activated).）	联系 Antom 技术支持并并提供 vaultingRequestId 和 vaultingResultCode。
`CARD_EXPIRED`	卡片已过期。（Card has expired.）	提示用户换卡重试。
`CARD_NOT_SUPPORTED`	不支持该卡片。（Card not supported.）	提示用户换卡。
`DO_NOT_HONOR`	支付被发卡行拒绝。（The payment is declined by the issuing bank.）	提示用户使用其他卡重试或联系发卡行。
`FRAUD_REJECT`	出于安全原因，该交易无法继续处理。如果用户已完成付款，交易金额将被退回。（The transaction cannot be further processed for security reasons. If the user has already paid for the transaction, the transaction will be refunded.）	联系 Antom 技术支持并提供 vaultingRequestId 和 vaultingResultCode.
`INVALID_CARD_NUMBER`	卡号无效。（invalid card number）	提示用户检查并重新输入卡号。
`INVALID_CVV`	CVV 无效。（The CVV code is invalid.）	提示用户检查并重新输入 CVV。
`INVALID_EXPIRATION_DATE`	有效期无效。（invalid expiration date.）	提示用户检查并重新输入有效期。
`LOST_CARD`	挂失卡（欺诈账户）。（Lost card, pick up card (fraud account)）	联系 Antom 技术支持并提供 vaultingRequestId 和 vaultingResultCode。
`NO_SELECTED_ACCOUNT`	持卡人选择了指定账户，但该账户不存在或不可用。（Used when the cardholder has selected specific account but does not have.）	联系 Antom 技术支持并提供 vaultingRequestId 和 vaultingResultCode。
`ORDER_IS_CLOSED`	订单已关闭。（The order is closed.）	使用新的 vaultingRequestId 重新发起绑卡请求。
`PAYMENT_AMOUNT_EXCEED_LIMIT`	支付金额超出限额。（Payment amount exceeds limit.）	联系 Antom 技术支持并提供 vaultingRequestId 和 vaultingResultCode。
`PAYMENT_COUNT_EXCEED_LIMIT`	支付次数超出限制。（Payment count exceeds limit.）	联系 Antom 技术支持并提供 vaultingRequestId 和 vaultingResultCode。
`PICKUP_CARD`	发卡行要求商户保留该卡片。通常发生于疑似伪卡或盗卡场景。（The card issuer requests that the merchant retain the card. This typically arises in cases of suspected counterfeit or stolen cards.）	联系 Antom 技术支持并提供 vaultingRequestId 和 vaultingResultCode。
`POLICY`	政策限制。（Policy.）	联系 Antom 技术支持并提供 vaultingRequestId 和 vaultingResultCode。
`PROCESS_FAIL`	发生通用业务失败。请勿重试。（A general business failure occurred. Don't retry.）	请勿重试。联系 Antom 技术支持，并提供 vaultingRequestId 和 vaultingResultCode。
`RESTRICTED_CARD`	发卡行限制了该卡片的使用场景或使用地区。（The card issuer has imposed restrictions on where the card can be used.）	联系 Antom 技术支持并提供 vaultingRequestId 和 vaultingResultCode。
`STOLEN_CARD`	被盗卡（欺诈账户）。（Stolen card, pick up (fraud account).）	联系 Antom 技术支持并提供 vaultingRequestId 和 vaultingResultCode。
`USER_BALANCE_NOT_ENOUGH`	用户余额不足，无法完成本次转账。（User balance is not enough for this transfer.）	建议用户更换支付方式或充值后重试。
`USER_PAYMENT_VERIFICATION_FAILED`	用户验证失败，例如 OTP 或 PIN 验证失败。（User verification like OTP or PIN verified failed.）	提示用户重新验证。
`VERIFY_TIMES_EXCEED_LIMIT`	验证码错误次数过多，用户必须获取新的验证码。（Verify code failed too many times, user must get a new code.）	提示用户获取新验证码。