attach

2026-08-26 08:47

重要说明：

所有请求及返回参数均严格以官网API文档为准。
API返回结果中可能包含未在文档中定义的字段。这些字段仅供内部调试使用，不保证稳定性及兼容性，请勿在生产环境中依赖这些字段，ZOLOZ保留随时修改或删除这些字段的权利，且无需另行通知。

概览

API URL：POST /api/v1/zoloz/applicant/attach
API 描述：该接口用于将一笔已成功完成的 RealID 交易数据关联到指定申请人。关联成功后，申请人可在 KYC 数据共享场景中使用相应的证件和人脸数据。

说明：

指定申请人和 RealID 交易必须属于当前商户。
RealID 交易必须已成功完成，并且产品类型必须为 RealID。
该接口支持使用相同的 applicantId 和 transactionId 重复调用。重复调用不会产生重复数据，即符合幂等性。
挂载同一证件类型的数据时，新交易中的证件数据将覆盖申请人已有的同类型证件；其他证件类型的数据将追加到申请人名下。
新交易中的人脸必须与申请人现有人脸属于同一人。校验通过后使用最新挂载的人脸结果；校验不通过时返回 FACE_MISMATCH。

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
bizId	String	32	是	-	业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ不校验该值的唯一性，商户侧需自行保证该业务ID的唯一性。	2026053000015
applicantId	String	50	是	-	需要挂载 KYC 数据的 ZOLOZ 申请人 ID。该申请人必须属于当前商户。	APHK_a1b2c3d4e5f6
transactionId	String	64	是	-	需要挂载的 RealID 交易 ID。该交易必须属于当前商户、已成功完成，且产品类型为 RealID。	G000000005FID2020030400000000000157****

返回参数

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

API请求结果，包含结果状态、结果码和结果消息。

{

"resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success"

}

transactionId

String

否

本次调用返回的交易ID，可用于业务追踪和问题排查。

说明：仅当交易进入处理阶段后系统才会返回transactionId。如果在开始处理交易之前发生错误，系统不会返回transactionId。包括但不限于以下情况：

请求参数非法，例如入参格式错误或缺失必传参数。
请求未能成功到达服务器，例如网络问题或网关故障。
系统限流导致请求被拒绝。

G000000005FID2020030400000000000157****

返回规则

处理结果	返回内容
挂载成功	返回 `result` 和本次 API 调用的 `transactionId`，其中 `result.resultCode=SUCCESS`。
幂等命中	返回 `result` 和本次 API 调用的 `transactionId`，其中 `result.resultCode=SUCCESS`，不会产生重复证件或人脸数据。
挂载失败	返回 `result` 和本次 API 调用的 `transactionId`，通过 `resultCode` 和 `resultMessage` 描述失败原因；交易数据不会挂载到申请人。

数据挂载规则

场景	处理结果
相同 `applicantId` 和 `transactionId` 重复调用	幂等返回成功，不产生重复数据。
新交易包含与申请人已有证件相同类型的证件	使用新交易中的证件数据覆盖已有同类型证件。
新交易包含申请人尚未挂载的证件类型	将该证件数据追加到申请人名下。
新交易中的人脸与申请人现有人脸属于同一人	使用最新挂载的人脸结果。
新交易中的人脸与申请人现有人脸不属于同一人	返回 `FACE_MISMATCH`，不挂载本次交易数据。

处理结果

根据请求结果执行下一步的响应动作，具体如下：

当result.resultCode=SUCCESS时，表示RealID 交易数据已成功关联到申请人，或本次请求幂等命中了已有挂载结果。
当result.resultCode=APPLICANT_NOT_FOUND时，表示applicantId 对应的申请人不存在，或不属于当前商户。
当result.resultCode=TRANSACTION_NOT_FOUND时，表示请求中的 transactionId 对应的 RealID 交易不存在，或不属于当前商户。
当result.resultStatus=F时，表示挂载失败，请根据返回的 resultCode 和 resultMessage 排查申请人、交易状态、产品类型、人脸一致性或请求参数。

API通用结果码

有关通用结果码的完整列表，请参见API通用结果码。

API特有结果码

Reusable RealID attach API的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	RealID 交易数据挂载成功，或幂等命中了已有挂载结果。
APPLICANT_NOT_FOUND	F	`applicantId` 对应的申请人不存在，或不属于当前商户。
TRANSACTION_NOT_FOUND	F	请求中的 `transactionId` 对应的交易不存在，或不属于当前商户。
TRANSACTION_NOT_SUCCESS	F	指定的 RealID 交易未成功完成，不能挂载到申请人。
TRANSACTION_NOT_REALID	F	指定交易不是 RealID 产品交易。
FACE_MISMATCH	F	新交易中的人脸与申请人现有人脸不是同一人，本次交易数据未挂载。
INVALID_ARGUMENT	F	输入参数无效。可能原因包括：缺少必填参数、字段超长等。具体错误信息请查看返回的`resultMessage`。
SYSTEM_ERROR	F	系统内部错误。有关错误详情，请查看返回的`resultMessage`。

代码示例

请求示例

copy
{
    "bizId": "2026053000015", 
    "applicantId": "APHK_a1b2c3d4e5f6", 
    "transactionId": "G000000005FID20200304000000000001570702"
}

返回示例

成功返回示例：

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "G000000005FID20200304000000000001570703"
}

失败返回示例：

copy
{
    "result": {
        "resultStatus": "F", 
        "resultCode": "TRANSACTION_NOT_SUCCESS", 
        "resultMessage": "The RealID transaction is not successful."
    }, 
    "transactionId": "G000000005FID20200304000000000001570704"
}