Notion 与 Persona / Sumsub / Stripe Identity 企业 KYC/KYB 身份核验、反欺诈人工复核(Manual Review)与合规审计闭环实战
一、为什么 FinTech 与 B2B 平台需要将 Persona / Sumsub / Stripe Identity 与 Notion 风控中枢打通? #
在跨境支付、金融科技(FinTech)、企业 SaaS 代理商准入与高客单价平台业务中,**KYC(个人实名认证)与 KYB(企业工商及受益所有人核验)**是业务合规放行的第一道防线。尽管技术团队普遍引入了 Persona、Sumsub 或 Stripe Identity 等自动化核验引擎,但在遇到边界案例与跨团队协作时仍面临三大核心难题:
- 人工复核(Manual Review)黑盒流转,大客户准入周期失控:自动核验引擎大约有
10%~18%的企业工商注册材料或实控人(UBO)证件会进入needs_review状态。若销售、合规官(Compliance Officer)与风控分析师缺少统一的协同台账,合规人员需要反复切换多套后台,而商务团队却对卡点毫不知情,导致大客户开户周期无限拉长; - 制裁名单(Sanctions / PEP)命中缺少实时阻断联动:当核验平台检测到申请方命中 OFAC 制裁名单、政治公众人物(PEP)或高风险欺诈设备指纹时,若仅停留在第三方平台邮件通知,极易被运营或财务团队在下游误放行开户或打款;
- 证件影印件与活体人脸 URL 直接回写 Notion 触发严重隐私合规违规:Persona / Sumsub 回调详情中可能附带身份证/护照原图预签名链接、完整证件号、家庭住址与生物特征摘要。根据 PCI-DSS、GDPR 与各国个人信息保护法,这类原始高敏 PII 与生物特征数据严禁持久化落盘到通用协作工具中。
将 Persona / Sumsub / Stripe Identity 与 Notion 企业合规与风控审核中枢 深度集成,可以在确保“零高敏证件留存”的前提下,打通“自动核验同步 -> 人工复核派单 -> 制裁命中页顶置顶熔断 -> 审核 SLA 倒计时”的标准化合规闭环:
| 企业 KYC/KYB 协同治理模式 | 邮件转发证件 PDF + 表格人工登记 | 仅在 Persona / Sumsub 后台处理 | 全量原始 Webhook 报文直写 Notion | 三表解耦合规中枢 + 零证件留存闭环(推荐) |
|---|---|---|---|---|
| 商务与合规跨部门协同 | 销售频繁催问进展,版本混乱易漏单 | 仅少数合规官有后台账号,业务全盲 | 高频 inquiry.started / step_completed 刷屏限流 | 按客户主档聚合核验状态与人工复核卡点 |
| 高敏 PII 与证件防泄漏安全 | 护照与营业执照原图在即时通讯群扩散 | 平台内受控,但缺少业务工单上下文 | 直接落盘证件号、人脸链接与 SSN 严重违规 | 网关强制剥离证件图片 URL 与证件号,仅存风险标签 |
| 制裁与高风险欺诈阻断速度 | 靠人工抽查,存在明显的风险时间窗 | 需登录第三方后台手动翻看风险队列 | 缺乏对上游开户页面的实时醒目警示 | 命中制裁/PEP 立即页顶置顶红色阻断告警块 |
| 人工复核 SLA 与放行门禁 | 无法统计合规审核平均响应耗时 | 难以与企业级合同签约、SSO 开通状态联动 | 缺少自动化放行条件聚合校验 | Formula 2.0 自动拦截未过审/超 SLA 实体 |
二、四步搭建“客户主体主档 × 核验工单快照 × 风险升级台账”三表模型 #
参照 Notion 企业级数据库架构设计规范 与 关系和汇总官方指南,建议搭建 企业客户主体主档库(DB_Customer_Entities)、KYC/KYB 核验工单快照库(DB_Verification_Inquiries) 与 制裁与人工复核升级台账(DB_Compliance_Escalations) 三表架构,并配合 企业级权限组配置 将数据严格隔离在合规与风控权限组内。
步骤 1:设计三表属性字段与幂等主键规范 #
务必严格贯彻**“核验凭据索引入库、原始生物与证件文件留存第三方合规金库”**的设计规范:Notion 仅保存 inquiry_id 外键索引、风险评分及脱敏后的拒因标签,绝不存储任何身份证件号或图像 URL:
| 所属数据库 | 属性名称 | 属性类型 | 合规审计与风控用途 |
|---|---|---|---|
DB_Customer_Entities | Entity_Name | Title | 企业法定名称或高净值个人脱敏代号(如 Acme Global PTE. LTD.) |
DB_Customer_Entities | Entity_Key | Rich Text | 业务系统主体唯一 ID(如 ent_904218) |
DB_Customer_Entities | Entity_Tier | Select | STANDARD / HIGH_VALUE_KYB / PEP_ENHANCED_DD |
DB_Customer_Entities | Compliance_Owner | Person | 负责最终合规签字放行的 AML/KYC 专员 |
DB_Customer_Entities | Submitted_At | Date | 客户首次提交 KYB/KYC 材料的 UTC 时间 |
DB_Customer_Entities | SLA_Hours | Number | 承诺人工复核处理 SLA(小时,如 24 或 48) |
DB_Verification_Inquiries | Inquiry_Title | Title | 核验工单摘要(如 [Sumsub] ent_904218 · KYB_L2) |
DB_Verification_Inquiries | Inquiry_Key | Rich Text | 幂等主键:{provider}:{inquiry_or_applicant_id} |
DB_Verification_Inquiries | Review_Status | Select | PENDING / NEEDS_REVIEW / APPROVED / DECLINED / EXPIRED |
DB_Verification_Inquiries | Risk_Score | Number | 归一化风险分(0 ~ 100,分值越高风险越大) |
DB_Verification_Inquiries | Sanctions_Hit | Checkbox | 是否命中制裁名单、PEP 或高危执法黑名单 |
DB_Verification_Inquiries | Updated_At | Date | 核验工单最近一次状态跃迁时间 |
DB_Verification_Inquiries | Entity_Relation | Relation | 双向关联至 DB_Customer_Entities |
DB_Compliance_Escalations | Escalation_Title | Title | 升级风控事件标题(如 [SANCTIONS_HIT] ent_904218 命中关联方观察名单) |
DB_Compliance_Escalations | Escalation_Key | Rich Text | 幂等防重主键:{provider}:{event_id} |
DB_Compliance_Escalations | Severity | Select | WARNING / CRITICAL |
DB_Compliance_Escalations | Resolution_Status | Select | OPEN / INVESTIGATING / CLEARED / BLOCKED |
DB_Compliance_Escalations | Sanitized_Reason | Rich Text | 剥离证件号、邮箱与文件 URL 后的合规拒因代码与脱敏摘要 |
DB_Compliance_Escalations | Entity_Relation | Relation | 双向关联至 DB_Customer_Entities |
步骤 2:配置 Persona-Signature / X-Payload-Digest 验签与零证件脱敏 #
- 原始字节流验签与防重放校验:Persona 使用
Persona-Signature(格式t=<ts>,v1=<hmac_sha256>),Sumsub 使用X-Payload-Digest(HMAC-SHA256 Hex)。网关必须在反序列化之前直接读取原始 HTTP Body 字节流完成签名校验,防止伪造APPROVED回调绕过风控; - 强制抹除证件 URL、邮箱与政府编号:建立白名单字段抽取与正则清洗双层防线,剥离
https://预签名文件链接、邮箱、护照/身份证号码(仅允许保留验证状态码如DOC_EXPIRED、SELFIE_MISMATCH、UBO_INCOMPLETE); - 过滤 Sandbox / Test 环境工单:检查 Persona 的
environment === "sandbox"或 SumsubsandboxMode === true标记并立即忽略,确保测试模拟数据不会混入正式合规审计台账。
步骤 3:规范高频中间步骤事件降噪与批注保护 #
- 屏蔽纯采集过程事件:用户上传身份证正面、等待活体检测自拍等过程中的
inquiry.started、verification.submitted事件频次极高且尚无核验结论,同步网关应直接返回200 OK丢弃;仅在状态跃迁至needs_review、approved、declined、expired或触发制裁命中时写入 Notion; - 保护合规官尽调(EDD)正文:网关仅调用
PATCH /v1/pages/{page_id}更新属性列,绝不覆盖DB_Customer_Entities页面内合规官撰写的企业股权穿透图解、外部工商查册截图与反洗钱评估结论。
步骤 4:利用 Notion-Version: 2026-03-11 在客户主档页顶置顶制裁与拒审熔断 #
所有 API 请求统一声明 Notion-Version: 2026-03-11(详见 Notion Views API 与 2026-03-11 接口升级工程实战)。当检测到 Sanctions_Hit == true 或人工复核最终裁定 DECLINED 时,网关除向 DB_Compliance_Escalations 幂等留痕外,立即调用 Blocks API 并指定 position: { type: "start" },在对应客户主档页面顶部置顶红色 callout 阻断提示,第一时间拦截下游业务开户与资金结算。
三、Python 生产级 KYC/KYB Webhook 验签与零证件留存同步实战 #
以下 Python 3.11+ 代码演示了 Persona 风格的 t=<ts>,v1=<sig> 防重放 HMAC-SHA256 验签、PII 与文件 URL 零留存清洗、429 指数退避重试(参考 Notion API 速率限制与容错架构),以及基于 Notion-Version: 2026-03-11 的三表幂等同步与页顶熔断逻辑:
# kyc_kyb_notion_sync.py — Python 3.11+ KYC/KYB Webhook 验签与 Notion 三表合规网关
import hashlib
import hmac
import os
import random
import re
import time
from datetime import datetime, timezone
from typing import Any, Dict, Optional
import requests
NOTION_TOKEN = os.environ["NOTION_TOKEN"]
KYC_WEBHOOK_SECRET = os.environ["KYC_WEBHOOK_SECRET"]
NOTION_ENTITIES_DS_ID = os.environ["NOTION_ENTITIES_DS_ID"]
NOTION_INQUIRIES_DS_ID = os.environ["NOTION_INQUIRIES_DS_ID"]
NOTION_ESCALATIONS_DS_ID = os.environ["NOTION_ESCALATIONS_DS_ID"]
NOTION_HEADERS = {
"Authorization": f"Bearer {NOTION_TOKEN}",
"Notion-Version": "2026-03-11",
"Content-Type": "application/json",
}
def verify_persona_signature(raw_body: bytes, sig_header: Optional[str], max_skew_sec: int = 300) -> bool:
if not sig_header or not KYC_WEBHOOK_SECRET:
return False
parts = {}
for item in sig_header.split(","):
if "=" in item:
k, v = item.strip().split("=", 1)
parts[k] = v
ts_str, sig_hex = parts.get("t"), parts.get("v1")
if not ts_str or not sig_hex or not ts_str.isdigit():
return False
if abs(int(time.time()) - int(ts_str)) > max_skew_sec:
return False
signed_payload = f"{ts_str}.".encode("utf-8") + raw_body
expected = hmac.new(KYC_WEBHOOK_SECRET.encode("utf-8"), signed_payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(sig_hex, expected)
def sanitize_kyc_reason(raw: str) -> str:
text = str(raw or "")
text = re.sub(r"https?://\S+", "[REDACTED_FILE_URL]", text)
text = re.sub(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b", "[REDACTED_EMAIL]", text)
text = re.sub(r"\b(\d{3}-\d{2}-\d{4}|[A-Z0-9]{8,18})\b", "[REDACTED_DOC_OR_ID]", text)
return text[:1500]
def notion_request(path: str, method: str = "GET", payload: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
url = f"https://api.notion.com/v1{path}"
for attempt in range(5):
resp = requests.request(method, url, headers=NOTION_HEADERS, json=payload, timeout=20)
if resp.status_code == 429 and attempt < 4:
retry_after = float(resp.headers.get("Retry-After", "1"))
jitter = random.uniform(0.15, 0.45)
time.sleep(retry_after + (2 ** attempt) * 0.35 + jitter)
continue
if not resp.ok:
raise RuntimeError(f"Notion API {resp.status_code}: {resp.text}")
return resp.json()
raise RuntimeError("Exceeded Notion API 429 retry budget")
def map_review_status(raw_status: str) -> str:
s = str(raw_status or "").lower()
if s in ("approved", "completed", "verified"):
return "APPROVED"
if s in ("declined", "rejected", "failed"):
return "DECLINED"
if s in ("needs_review", "manual_review", "on_hold"):
return "NEEDS_REVIEW"
if s == "expired":
return "EXPIRED"
return "PENDING"
def sync_kyc_event(event: Dict[str, Any]) -> Dict[str, Any]:
if event.get("environment") == "sandbox" or event.get("sandboxMode") is True:
return {"skipped": True, "reason": "sandbox-inquiry"}
raw_status = str(event.get("status", "")).lower()
if raw_status in ("created", "started", "step_completed"):
return {"skipped": True, "reason": "noisy-intermediate-step"}
provider = str(event.get("provider", "Persona"))
entity_key = str(event["entity_key"])
entity_name = str(event.get("entity_name") or entity_key)[:120]
inquiry_id = str(event["inquiry_id"])
event_id = str(event["event_id"])
mapped_status = map_review_status(raw_status)
sanctions_hit = bool(event.get("sanctions_hit", False))
risk_score = max(0.0, min(100.0, float(event.get("risk_score", 0.0))))
now_iso = datetime.now(timezone.utc).isoformat()
# 1. 查找或创建客户主体主档 (DB_Customer_Entities)
ent_q = notion_request(
f"/data_sources/{NOTION_ENTITIES_DS_ID}/query",
"POST",
{"filter": {"property": "Entity_Key", "rich_text": {"equals": entity_key}}, "page_size": 1},
)
if ent_q.get("results"):
ent_page_id = ent_q["results"][0]["id"]
else:
created_ent = notion_request(
"/pages",
"POST",
{
"parent": {"type": "data_source_id", "data_source_id": NOTION_ENTITIES_DS_ID},
"properties": {
"Entity_Name": {"title": [{"text": {"content": entity_name}}]},
"Entity_Key": {"rich_text": [{"text": {"content": entity_key}}]},
"Entity_Tier": {"select": {"name": "HIGH_VALUE_KYB"}},
"Submitted_At": {"date": {"start": now_iso}},
"SLA_Hours": {"number": 24},
},
},
)
ent_page_id = created_ent["id"]
# 2. 幂等同步核验工单快照 (DB_Verification_Inquiries)
inquiry_key = f"{provider.lower()}:{inquiry_id}"
inq_q = notion_request(
f"/data_sources/{NOTION_INQUIRIES_DS_ID}/query",
"POST",
{"filter": {"property": "Inquiry_Key", "rich_text": {"equals": inquiry_key}}, "page_size": 1},
)
inq_props = {
"Inquiry_Title": {"title": [{"text": {"content": f"[{provider}] {entity_key}"}}]},
"Inquiry_Key": {"rich_text": [{"text": {"content": inquiry_key}}]},
"Review_Status": {"select": {"name": mapped_status}},
"Risk_Score": {"number": round(risk_score, 2)},
"Sanctions_Hit": {"checkbox": sanctions_hit},
"Updated_At": {"date": {"start": now_iso}},
"Entity_Relation": {"relation": [{"id": ent_page_id}]},
}
if inq_q.get("results"):
notion_request(f"/pages/{inq_q['results'][0]['id']}", "PATCH", {"properties": inq_props})
else:
notion_request(
"/pages",
"POST",
{"parent": {"type": "data_source_id", "data_source_id": NOTION_INQUIRIES_DS_ID}, "properties": inq_props},
)
# 3. 制裁命中、拒审或人工复核升级时留痕并置顶告警
should_escalate = sanctions_hit or mapped_status in ("DECLINED", "NEEDS_REVIEW")
if should_escalate:
esc_key = f"{provider.lower()}:{event_id}"
esc_q = notion_request(
f"/data_sources/{NOTION_ESCALATIONS_DS_ID}/query",
"POST",
{"filter": {"property": "Escalation_Key", "rich_text": {"equals": esc_key}}, "page_size": 1},
)
if not esc_q.get("results"):
severity = "CRITICAL" if (sanctions_hit or mapped_status == "DECLINED") else "WARNING"
tag = "SANCTIONS_HIT" if sanctions_hit else mapped_status
clean_reason = sanitize_kyc_reason(event.get("reason_codes") or f"Inquiry transitioned to {tag}")
notion_request(
"/pages",
"POST",
{
"parent": {"type": "data_source_id", "data_source_id": NOTION_ESCALATIONS_DS_ID},
"properties": {
"Escalation_Title": {"title": [{"text": {"content": f"[{tag}] {entity_key}"}}]},
"Escalation_Key": {"rich_text": [{"text": {"content": esc_key}}]},
"Severity": {"select": {"name": severity}},
"Resolution_Status": {"select": {"name": "OPEN"}},
"Sanitized_Reason": {"rich_text": [{"text": {"content": clean_reason}}]},
"Entity_Relation": {"relation": [{"id": ent_page_id}]},
},
},
)
if severity == "CRITICAL":
notion_request(
f"/blocks/{ent_page_id}/children",
"PATCH",
{
"position": {"type": "start"},
"children": [
{
"object": "block",
"type": "callout",
"callout": {
"icon": {"type": "emoji", "emoji": "🛑"},
"color": "red_background",
"rich_text": [
{
"type": "text",
"text": {
"content": f"[KYC/KYB 合规熔断] 实体 {entity_key} 触发 {tag}(脱敏原因:{clean_reason}),请立即冻结开户放行与资金结算!"
},
}
],
},
}
],
},
)
return {"ok": True, "ent_page_id": ent_page_id, "inquiry_key": inquiry_key, "status": mapped_status}
四、Formula 2.0 实战:KYC/KYB 准入放行门禁与人工复核 SLA 超时预警 #
在 DB_Customer_Entities 中新增 Formula 2.0 属性 KYC/KYB 合规准入放行门禁(语法细节参阅 Notion Formula 2.0 函数与正则表达式速查手册 与 官方公式指南),自动关联制裁命中标记、最新核验状态、风险评分阈值、未解升级工单以及人工复核 SLA 耗时:
| 合规准入放行维度 | Formula 2.0 核心判定条件 | 合规与反欺诈风控收益 |
|---|---|---|
| 制裁名单命中或严重升级未结 | sanctionedInqs.length() > 0 \|\| criticalEscs.length() > 0 | 触发最高优先级红色熔断,禁止运营或财务为客户开通交易与结算权限 |
| 核验工单被拒审或风险分过高 | declinedInqs.length() > 0 \|\| maxRisk >= 75 | 强制拦截高风险主体,必须由 AML 合规主管线下复核签字后方可解除 |
| 人工复核超时 SLA | reviewInqs.length() > 0 && elapsedHours > slaHours | 自动标红催办积压的人工复核工单,避免大客户长期卡单流失 |
| 全部过审且无风险升级 | approvedInqs.length() > 0 && openEscs.length() == 0 | 自动亮绿灯放行,向销售与交付团队同步“合规就绪”信号 |
lets(
inqs, prop("Verification_Inquiries"),
escs, prop("Compliance_Escalations"),
slaHours, if(empty(prop("SLA_Hours")), 24, prop("SLA_Hours")),
submittedAt, prop("Submitted_At"),
elapsedHours, if(empty(submittedAt), 0, dateBetween(now(), submittedAt, "hours")),
sanctionedInqs, inqs.filter(current.prop("Sanctions_Hit") == true),
declinedInqs, inqs.filter(current.prop("Review_Status") == "DECLINED"),
reviewInqs, inqs.filter(current.prop("Review_Status") == "NEEDS_REVIEW"),
approvedInqs, inqs.filter(current.prop("Review_Status") == "APPROVED"),
maxRisk, if(inqs.length() == 0, 0, inqs.map(current.prop("Risk_Score")).max()),
openEscs, escs.filter(current.prop("Resolution_Status") != "CLEARED"),
criticalEscs, openEscs.filter(current.prop("Severity") == "CRITICAL"),
ifs(
sanctionedInqs.length() > 0 || criticalEscs.length() > 0,
style("🛑 合规阻断:命中制裁名单或存在未结高危升级,严禁开户与资金结算", "red", "bold", "red_background"),
declinedInqs.length() > 0 || maxRisk >= 75,
style("🚨 核验未通过/高风险(峰值风险分 " + format(round(maxRisk)) + "):已触发反欺诈拦截", "red", "bold"),
reviewInqs.length() > 0 && elapsedHours > slaHours,
style("⏰ 人工复核超时(已等待 " + format(elapsedHours) + "h > " + format(slaHours) + "h SLA):请合规团队优先处理", "red", "bold"),
reviewInqs.length() > 0,
style("⏳ 人工复核进行中(已耗时 " + format(elapsedHours) + "h / " + format(slaHours) + "h SLA)", "orange"),
inqs.length() == 0,
style("⚪ 尚未收到 Persona / Sumsub / Stripe Identity 核验回调", "gray"),
approvedInqs.length() > 0 && openEscs.length() == 0,
style("🟢 KYC/KYB 合规过审放行(最高风险分 " + format(round(maxRisk)) + ")", "green", "bold", "green_background"),
style("🟡 核验流转中:等待客户补充证件或二次复审", "orange")
)
)
建议将本方案与 Notion 与 WorkOS 企业级 SSO / SCIM 目录同步与大客户安全入驻实战、Notion 与 DocuSign / PandaDoc 企业电子签章与 CLM 合同治理实战 以及 Notion 与 Anrok / Avalara / Stripe Tax 全球 SaaS 销售税监控闭环实战 组合部署,形成完整的企业客户安全入驻与金融合规防线。
五、Persona / Sumsub / Stripe Identity 同步 Notion 常见故障排查 #
在落地企业 KYC/KYB 协同链路后,以下四类常见异常需重点排查(完整诊断指南请参阅 Notion 常见报错与故障诊断手册):
- 误将护照、营业执照预签名下载链接写入 Notion 页面:直接透传 Webhook 回调中的
document_front_url或selfie_url,不仅导致链接数小时后失效,更违反最小化数据留存规范。解法:在入库前强制调用sanitize_kyc_reason()抹除所有http/httpsURL 与证件编号,仅保存inquiry_id供合规官跳转原平台查阅。 Persona-Signature验签持续返回401:FastAPI / Flask 在校验前提前调用了request.get_json()并重新序列化为字符串,改变了原始请求体的空格或 Unicode 转义形式。解法:直接读取await request.body()原始字节流执行 HMAC-SHA256 校验后再进行 JSON 解析。- 客户反复重试人脸自拍导致 Notion 触发
429限流:未对inquiry.started、step_completed等高频率过程事件降噪,单次认证高峰即发起十余次写库。解法:网关入口仅放行needs_review、approved、declined、expired及制裁告警事件,其余过程态直接返回200 OK忽略。 - Sandbox 测试账号混淆正式开户准入看板:研发联调时使用测试身份证触发
SANCTIONS_HIT并推送到了生产权限组空间。解法:在入口显式校验environment == "sandbox"或sandboxMode is True并跳过同步。
核心手册与速查工具矩阵
高频速查手册与生产力工具直达常见问题与答疑 (FAQ)
高频疑难解析与避坑指南完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。