将验证状态映射到您的产品状态

您的产品状态应仅根据一个字段改变：status这是验证的结果，取十个值之一，从not_started到approved。 店铺checkStatus旁边会记录自动检查的结果，因为这是两者结果不一致时你唯一能找到的解释。它们出现分歧的频率比工程师预期的要高，而这正是设计使然。

实际上，这意味着三件事：绘制十个地图中的每一个status在你的系统中，值恰好对应一个状态，取最新值status从verification.status_updated使用 webhook 或轮询方式，而不是从收到的第一个事件开始，并使用reasonCode（绝不能只看原始状态）来决定如何告知申请人。本文的其余部分会将此信息转化为您可以直接使用的表格和您可以修改的代码。

为什么有两个字段而不是一个？

因为验证结果由两部分决定。自动化检查会读取文件、查询政府记录、进行人脸比对并读取芯片信息。然后，您的工作流程决策规则或团队成员会决定如何处理此人。验证生命周期文档 （在新标签页中打开）为每个问题都设置了单独的字段。

status规则的制定遵循固定的顺序，首先适用的规则优先：首先是审核员的决定，然后是工作流程的决定，最后是仅凭检查结果做出的决定。checkStatus不会因为规则或审核员而改变。因此，即使申请人的面部特征与照片不符，但如果审核员在视频通话后批准了该申请人，最终结果仍然是：status: "approved"和checkStatus: "failed"两者都正确，如果只存储第一个，以后就无法解释为什么允许这种例外情况。

每个状态应该如何与您的产品对应？

以下是一个示例贷款应用程序的映射图。账户状态和消息均为示例；右侧列是需要复制的部分。

即使你把表格中的每个州都重新命名，表格中的两个设计选择也值得借鉴。

首先，每个值对应一个状态，即使两个值看起来相同。很容易会想把两个值合并起来。in_review进入processing因为两者都表示“等待”。请将它们分开：in_review这意味着你团队中的某人需要做出决定，这是一个内部队列指标，而processing平台运行正常吗？

第二，declined是一种状态，并附带原因。政府数据库中没有的ID是……declined和reasonCode: "identity_not_found"，而不是一种单独的状态。分支应基于代码，而不是基于状态的激增。

处理过程实际上会等待什么？

通常情况下，只需要进行检查。但如果你的工作流程将决策推迟到较慢的环节，processing持续时间更长，状态端点包括waitingOn说什么。价值观包括"screening"（制裁，） PEP 或不良媒体筛查）和"key_people"（企业申请中的董事和所有者完成他们自己的核实过程）；null表示检查仍在运行。状态端点参考 （在新标签页中打开）列出了这些检查。

这个字段可以让申请人筛选页面显示比加载指示器更有用的信息，也能让运营团队了解为什么某个业务申请会被拒绝。processing两天。

为什么 verification.completed 并不总是最终结果？

因为它描述的是检查过程，而不是最终决定。这些事件verification.completed，.failed，.not_found和.error检查完成后立即发送。如果您的工作流包含决策规则，则在工作流做出决策之前发送，并且这些规则会立即发送。status仅反映支票金额。

判决随后出炉。verification.status_updated， 和source: "workflow"当审核员在仪表板中做出决定时，也会触发相同的事件（source: "dashboard"或者由后端通过审核来决定 API （source: "api"它携带previousStatus以及新的status而且，与大多数活动不同，它是以扁平形式交付的，而不是用包装纸包裹的。data正如webhooks 文档中 （在新标签页中打开）所述，对象。

一个具体的例子能使陷阱更加明确。工作流程会拒绝任何与监控名单匹配的申请人。申请人通过了所有审核：verification.completed到达时status: "approved"几秒钟后，筛查等待结束，工作流程也随之减少。verification.status_updated到达时status: "declined"和source: "workflow"如果你的客服人员在第一次活动中就为客户办理了入职手续，那么你就为一位违反你公司政策的客户办理了入职手续。

规则：如果你的工作流程有决策规则，请谨慎处理。verification.status_updated（或新的民意调查）作为信息来源status如果没有决策规则，检查本身就是决策。verification.completed除非审阅者之后修改，否则此版本为最终版本。

你应该告诉申请人什么？

使用reasonCode选择消息并使用reason小心。

在failed或者not_found查看，reason这份文件是为申请人编写的：使用通俗易懂的语言，说明哪些地方不匹配以及下一步该怎么做，不涉及评分、门槛，也不引用任何政府记录。您可以直接展示这份文件。

在error结果，reason是为您写的。它可能写着“充值余额”或“联系我们”。 Toden 这对申请人来说毫无意义。向他们显示一条通用消息并进行路由。reason致你的团队。

随着时间的推移，可能会添加新的代码，因此请将无法识别的代码映射到通用故障消息，而不是映射到代码中的错误。

这用代码怎么写？

一个用 TypeScript 编写的处理程序，用于应用上述规则。accounts通话只是你坚持不懈的占位符。

type Status =
  | 'not_started' | 'in_progress' | 'processing' | 'in_review'
  | 'awaiting_resubmission' | 'approved' | 'declined'
  | 'abandoned' | 'expired' | 'error';

const ACCOUNT_STATE: Record<Status, string> = {
  not_started: 'kyc_invited',
  in_progress: 'kyc_in_progress',
  processing: 'kyc_checking',
  in_review: 'kyc_manual_review',
  awaiting_resubmission: 'kyc_action_needed',
  approved: 'kyc_passed',
  declined: 'kyc_failed',
  abandoned: 'kyc_dropped',
  expired: 'kyc_link_expired',
  error: 'kyc_retry',
};

export async function applyVerificationStatus(event: {
  verificationId: string;
  status: Status;
  checkStatus?: string;
  reasonCode?: string | null;
  reason?: string | null;
}) {
  const state = ACCOUNT_STATE[event.status] ?? 'kyc_checking'; // unknown value: keep waiting
  await accounts.updateByVerificationId(event.verificationId, {
    kycState: state,
    kycStatus: event.status,
    kycCheckStatus: event.checkStatus ?? null, // the explanation, kept for audit
    kycReasonCode: event.reasonCode ?? null,
    kycReason: event.reason ?? null,
  });
}

从两者的角度来看verification.status_updated处理程序和轮询路径，因此两者不会发生偏移。对重复的 webhook 发送进行去重。X-Myaza-Delivery调用前请先添加头部信息。

当验证信息被发送回来时会发生什么？

它会保留自己的ID。当审核员发送验证信息后，如果申请人重新提交申请，则同一份验证信息会启动新的验证尝试：attempt增加1，checkStatus返回pending然后检查再次运行。您的映射处理这种情况时没有特殊处理：状态从awaiting_resubmission到processing然后再次稳定下来。将您的记录录入到verificationId关键在于，它不是基于“该用户的最新验证”查询，而是基于其他因素。

要了解全貌，包括之前的每一次尝试和每一个决定，请阅读以下内容。GET /api/kyc/verifications/:id从您的后端使用密钥返回。review和statusHistory按验证结果参考 （在新标签页中打开）中的描述，最新结果优先。

检查清单

• 每个产品状态status价值，与in_review和processing分开存放。

• checkStatus，reason和reasonCode存放于旁边status， 总是。

• 最新的status摘自verification.status_updated或者在工作流程包含决策规则时进行轮询。

• 申请人副本由……选择reasonCode；reason仅在failed和not_found。

• 未知status或者reasonCode处理结果为“继续等待”或“一般故障”，绝不会作为崩溃处理。

• 记录以……为键verificationId因此，重新提交会更新同一行。

开发者中心链接了此处使用的 webhook 和状态引用。