要将用户升级到更高的 KYC 级别（L2+），您需要上传支持文档，例如身份证图像、地址证明和资金来源文档。
文档必须是清晰、未经更改的 JPG、PNG 或 PDF 格式图像，每个文件最大 10MB。
文档类型
个人文档
带照片的政府签发的身份证
PASSPORT - 护照DRIVER_LICENSE - 驾照NUIP - 哥伦比亚身份证INE - 墨西哥选举身份证IFE - 墨西哥选举身份证（旧）RFC - 墨西哥税号SSN - 美国社会保障CURP - 墨西哥人口登记CPF - 巴西税号DNI - 国民身份证DUI - 唯一身份证件
要求：
- 正面图像（始终必需）
- 背面图像（如适用）
- 清晰、可读的文本
- 所有角落可见
- 无眩光或阴影
显示当前地址的文档
PROVE_OF_ADDRESS_UTILITY_BILL - 水电费账单PROVE_OF_ADDRESS_BANK_STATEMENT - 银行对账单PROVE_OF_ADDRESS_LEASE_AGREEMENT - 租赁协议
要求：
- 在过去 3 个月内签发
- 显示全名
- 显示完整地址
- 来自认可的提供商/机构
收入来源文档
SOURCE_OF_FUNDS_BANK_STATEMENT - 银行对账单SOURCE_OF_FUNDS_PAYSLIP - 工资单- 就业信函
- 商业财务报表
要求：
- 最近的（最近 3 个月）
- 显示定期收入
- 与声明的来源匹配
- 来自官方机构
公司文档
NIT - 哥伦比亚税号PROOF_OF_COMPANY_FORMATION - 成立文档ARTICLES_OF_INCORPORATION - 公司章程INCORPORATION_DOCUMENTS - 法律文档KYB_REPORT - 了解您的业务报告OTHER - 其他商业文档
上传个人文档
POST /api/v2/users/person/document
Content-Type: multipart/form-data
const uploadDocument = async (userId, documentType, frontFile, backFile = null) => {
const formData = new FormData();
formData.append('userId', userId);
formData.append('documentType', documentType);
formData.append('frontDocument', frontFile);
if (backFile) {
formData.append('backDocument', backFile);
}
const response = await fetch(
'https://teste-94u93qnn.uc.gateway.dev/api/v2/users/person/document',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`
},
body: formData
}
);
if (!response.ok) {
const error = await response.json();
throw new Error(`上传失败: ${error.message}`);
}
return await response.json();
};
// 使用
const frontImage = new File([blob], 'passport-front.jpg', { type: 'image/jpeg' });
await uploadDocument(userId, 'PASSPORT', frontImage);
上传公司文档
POST /api/v2/users/company/document
Content-Type: multipart/form-data
const uploadCompanyDocument = async (userId, documentType, documentFile) => {
const formData = new FormData();
formData.append('userId', userId);
formData.append('documentType', documentType);
formData.append('frontDocument', documentFile);
const response = await fetch(
'https://teste-94u93qnn.uc.gateway.dev/api/v2/users/company/document',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`
},
body: formData
}
);
return await response.json();
};
文档指南
照片质量
✅ 良好：
- 清晰、聚焦的图像
- 所有文本可读
- 所有角落可见
- 良好的照明
- 原始颜色
- 最低 300 DPI
❌ 不良：
- 模糊或失焦
- 眩光或阴影
- 裁剪的角落
- 黑白副本
- 截图
- 低分辨率
接受的格式：
- JPEG/JPG（推荐）
- PNG
- PDF（用于对账单/信函）
大小限制：
- 最大：每个文件 10 MB
- 最小：100 KB
- 推荐：1-3 MB
- 无编辑或更改
- 仅当前/有效文档
- 完整文档可见
- 原始文档（无复印件）
- 首选彩色图像
- 最近的照片（地址证明在 6 个月内）
拍摄好照片
客户端验证
上传前验证文档：
const validateDocument = (file) => {
const errors = [];
// 文件大小
const maxSize = 10 * 1024 * 1024; // 10MB
if (file.size > maxSize) {
errors.push('文件太大。最大 10MB。');
}
if (file.size < 100 * 1024) {
errors.push('文件太小。最小 100KB。');
}
// 文件类型
const allowedTypes = ['image/jpeg', 'image/jpg', 'image/png', 'application/pdf'];
if (!allowedTypes.includes(file.type)) {
errors.push('无效的文件类型。使用 JPG、PNG 或 PDF。');
}
// 图像尺寸（对于图像）
if (file.type.startsWith('image/')) {
const img = new Image();
img.src = URL.createObjectURL(file);
img.onload = () => {
if (img.width < 800 || img.height < 600) {
errors.push('图像分辨率太低。最低 800x600。');
}
};
}
return errors;
};
跟踪上传状态
监控文档处理：
const trackDocumentStatus = async (userId) => {
// 获取用户详情
const user = await fetch(`/api/v2/users/${userId}`, {
headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());
console.log('当前状态:', user.status);
console.log('访问级别:', user.accessLevel);
console.log('备注:', user.note);
// 如果待处理，检查合规 URL
if (user.status === 'PENDING') {
console.log('在以下位置完成 KYC:', user.complianceUrl);
}
return user;
};
文档更新的 Webhooks
订阅 USER 事件以接收通知：
{
"event": "user.kyc_submitted",
"data": {
"userId": "user-id",
"documentsSubmitted": ["PASSPORT", "PROVE_OF_ADDRESS_UTILITY_BILL"],
"status": "PENDING"
}
}
{
"event": "user.kyc_approved",
"data": {
"userId": "user-id",
"previousLevel": "L1",
"newLevel": "L2",
"status": "ACTIVE"
}
}
处理拒绝
如果文档被拒绝：
{
"event": "user.kyc_rejected",
"data": {
"userId": "user-id",
"reason": "文档图像质量不足",
"rejectedDocuments": ["PASSPORT"],
"status": "REJECTED"
}
}
- 通知用户拒绝
- 从
reason 解释具体问题
- 请求重新提交
- 提供上传指南
- 监控重新提交
文档保留
文档根据监管要求安全存储和保留。用户可以根据 GDPR/隐私法请求删除。
最佳实践
- 显示实时上传进度
- 提交前预览图像
- 提供照片指南
- 如果质量差，允许重拍
- 在步骤之间保存进度
- 使用设备相机捕获
- 自动优化图像大小
- 上传前压缩
- 处理网络中断
- 显示数据使用估算
- 首先在客户端验证文件
- 显示特定错误消息
- 允许轻松重试
- 失败时保留表单数据
- 记录上传错误
合规 URL 替代方案
不要自己处理文档上传，而是将用户重定向到 KillB 的合规 URL：
const user = await createUser(userData);
// 重定向到 KillB 的 KYC 门户
window.location.href = user.complianceUrl;
- KillB 处理整个 KYC 流程
- 内置文档捕获
- 自动验证
- 移动优化
- 多语言支持
- 包含活体检测
使用合规 URL 是最简单的集成路径。用户在 KillB 的门户上完成 KYC，您会收到 webhook 通知。
下一步
