Начало работы
Интеграция / SDK
Проверка пользователей
Верификация бизнеса
Мониторинг транзакций
Журнал измененийcurl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "11111111-2222-3333-4444-555555555555",
"vendor_data": "user-123",
"callback": "https://example.com/verification/callback",
"callback_method": "both",
"metadata": {"user_type": "premium", "account_id": "ABC123"},
"language": "en",
"contact_details": {
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
},
"expected_details": {
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
}'from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.create(
workflow_id="11111111-2222-3333-4444-555555555555",
vendor_data="user-123",
callback="https://example.com/verification/callback",
callback_method="both",
metadata={"user_type": "premium", "account_id": "ABC123"},
language="en",
contact_details={
"email": "john.doe@example.com",
"send_notification_emails": True,
"email_lang": "en",
"phone": "+14155552671",
},
expected_details={
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"],
},
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.sessions.create({
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
},
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{
WorkflowID: "11111111-2222-3333-4444-555555555555",
VendorData: didit.String("user-123"),
Callback: didit.String("https://example.com/verification/callback"),
CallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod("both")),
Metadata: didit.Some[any](map[string]any{"user_type": "premium", "account_id": "ABC123"}),
Language: didit.Some(didit.SessionsCreateParamsLanguage("en")),
ContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{
Email: didit.String("john.doe@example.com"),
SendNotificationEmails: didit.Bool(true),
EmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang("en")),
Phone: didit.String("+14155552671"),
}),
ExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{
FirstName: didit.String("John"),
LastName: didit.String("Doe"),
DateOfBirth: didit.String("1990-05-15"),
Nationality: didit.String("USA"),
IDCountry: didit.String("USA"),
ExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{"P", "ID"}),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SessionsCreateParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.sessions().create(SessionsCreateParams.builder()
.workflowId("11111111-2222-3333-4444-555555555555")
.vendorData("user-123")
.callback("https://example.com/verification/callback")
.callbackMethod(SessionsCreateParams.CallbackMethod.of("both"))
.metadata(Map.of("user_type", "premium", "account_id", "ABC123"))
.language(SessionsCreateParams.Language.of("en"))
.contactDetails(SessionsCreateParams.ContactDetails.builder()
.email("john.doe@example.com")
.sendNotificationEmails(true)
.emailLang(SessionsCreateParams.ContactDetails.EmailLang.of("en"))
.phone("+14155552671")
.build())
.expectedDetails(SessionsCreateParams.ExpectedDetails.builder()
.firstName("John")
.lastName("Doe")
.dateOfBirth(LocalDate.parse("1990-05-15"))
.nationality("USA")
.idCountry("USA")
.expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("P"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("ID")))
.build())
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->sessions->create([
'workflow_id' => '11111111-2222-3333-4444-555555555555',
'vendor_data' => 'user-123',
'callback' => 'https://example.com/verification/callback',
'callback_method' => 'both',
'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],
'language' => 'en',
'contact_details' => [
'email' => 'john.doe@example.com',
'send_notification_emails' => true,
'email_lang' => 'en',
'phone' => '+14155552671',
],
'expected_details' => [
'first_name' => 'John',
'last_name' => 'Doe',
'date_of_birth' => '1990-05-15',
'nationality' => 'USA',
'id_country' => 'USA',
'expected_document_types' => ['P', 'ID'],
],
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.create(
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
}
)
puts result.to_husing System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Sessions.CreateAsync(new SessionsCreateParams
{
WorkflowId = "11111111-2222-3333-4444-555555555555",
VendorData = "user-123",
Callback = "https://example.com/verification/callback",
CallbackMethod = new SessionsCreateParamsCallbackMethod("both"),
Metadata = new Dictionary<string, object> { ["user_type"] = "premium", ["account_id"] = "ABC123" },
Language = new SessionsCreateParamsLanguage("en"),
ContactDetails = new SessionsCreateParamsContactDetails
{
Email = "john.doe@example.com",
SendNotificationEmails = true,
EmailLang = new SessionsCreateParamsContactDetailsEmailLang("en"),
Phone = "+14155552671",
},
ExpectedDetails = new SessionsCreateParamsExpectedDetails
{
FirstName = "John",
LastName = "Doe",
DateOfBirth = "1990-05-15",
Nationality = "USA",
IdCountry = "USA",
ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { "P", "ID" },
},
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"session_id": "11111111-2222-3333-4444-555555555555",
"session_number": 43762,
"session_token": "3FaJ9wLqX2Mz",
"url": "https://verify.didit.me/en/session/3FaJ9wLqX2Mz",
"vendor_data": "user-123",
"metadata": {
"user_type": "premium",
"account_id": "ABC123"
},
"status": "Not Started",
"workflow_id": "11111111-2222-3333-4444-555555555555",
"workflow_version": 3,
"callback": "https://example.com/verification/callback"
}Create Session API: запуск KYC и KYB верификации в Didit
POST /v3/session/ запускает сессию верификации Didit: единый KYC и KYB, оплата за использование, инференс до 2 с, $10 кредитов в месяц.
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "11111111-2222-3333-4444-555555555555",
"vendor_data": "user-123",
"callback": "https://example.com/verification/callback",
"callback_method": "both",
"metadata": {"user_type": "premium", "account_id": "ABC123"},
"language": "en",
"contact_details": {
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
},
"expected_details": {
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
}'from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.create(
workflow_id="11111111-2222-3333-4444-555555555555",
vendor_data="user-123",
callback="https://example.com/verification/callback",
callback_method="both",
metadata={"user_type": "premium", "account_id": "ABC123"},
language="en",
contact_details={
"email": "john.doe@example.com",
"send_notification_emails": True,
"email_lang": "en",
"phone": "+14155552671",
},
expected_details={
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"],
},
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.sessions.create({
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
},
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{
WorkflowID: "11111111-2222-3333-4444-555555555555",
VendorData: didit.String("user-123"),
Callback: didit.String("https://example.com/verification/callback"),
CallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod("both")),
Metadata: didit.Some[any](map[string]any{"user_type": "premium", "account_id": "ABC123"}),
Language: didit.Some(didit.SessionsCreateParamsLanguage("en")),
ContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{
Email: didit.String("john.doe@example.com"),
SendNotificationEmails: didit.Bool(true),
EmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang("en")),
Phone: didit.String("+14155552671"),
}),
ExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{
FirstName: didit.String("John"),
LastName: didit.String("Doe"),
DateOfBirth: didit.String("1990-05-15"),
Nationality: didit.String("USA"),
IDCountry: didit.String("USA"),
ExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{"P", "ID"}),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SessionsCreateParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.sessions().create(SessionsCreateParams.builder()
.workflowId("11111111-2222-3333-4444-555555555555")
.vendorData("user-123")
.callback("https://example.com/verification/callback")
.callbackMethod(SessionsCreateParams.CallbackMethod.of("both"))
.metadata(Map.of("user_type", "premium", "account_id", "ABC123"))
.language(SessionsCreateParams.Language.of("en"))
.contactDetails(SessionsCreateParams.ContactDetails.builder()
.email("john.doe@example.com")
.sendNotificationEmails(true)
.emailLang(SessionsCreateParams.ContactDetails.EmailLang.of("en"))
.phone("+14155552671")
.build())
.expectedDetails(SessionsCreateParams.ExpectedDetails.builder()
.firstName("John")
.lastName("Doe")
.dateOfBirth(LocalDate.parse("1990-05-15"))
.nationality("USA")
.idCountry("USA")
.expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("P"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("ID")))
.build())
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->sessions->create([
'workflow_id' => '11111111-2222-3333-4444-555555555555',
'vendor_data' => 'user-123',
'callback' => 'https://example.com/verification/callback',
'callback_method' => 'both',
'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],
'language' => 'en',
'contact_details' => [
'email' => 'john.doe@example.com',
'send_notification_emails' => true,
'email_lang' => 'en',
'phone' => '+14155552671',
],
'expected_details' => [
'first_name' => 'John',
'last_name' => 'Doe',
'date_of_birth' => '1990-05-15',
'nationality' => 'USA',
'id_country' => 'USA',
'expected_document_types' => ['P', 'ID'],
],
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.create(
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
}
)
puts result.to_husing System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Sessions.CreateAsync(new SessionsCreateParams
{
WorkflowId = "11111111-2222-3333-4444-555555555555",
VendorData = "user-123",
Callback = "https://example.com/verification/callback",
CallbackMethod = new SessionsCreateParamsCallbackMethod("both"),
Metadata = new Dictionary<string, object> { ["user_type"] = "premium", ["account_id"] = "ABC123" },
Language = new SessionsCreateParamsLanguage("en"),
ContactDetails = new SessionsCreateParamsContactDetails
{
Email = "john.doe@example.com",
SendNotificationEmails = true,
EmailLang = new SessionsCreateParamsContactDetailsEmailLang("en"),
Phone = "+14155552671",
},
ExpectedDetails = new SessionsCreateParamsExpectedDetails
{
FirstName = "John",
LastName = "Doe",
DateOfBirth = "1990-05-15",
Nationality = "USA",
IdCountry = "USA",
ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { "P", "ID" },
},
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"session_id": "11111111-2222-3333-4444-555555555555",
"session_number": 43762,
"session_token": "3FaJ9wLqX2Mz",
"url": "https://verify.didit.me/en/session/3FaJ9wLqX2Mz",
"vendor_data": "user-123",
"metadata": {
"user_type": "premium",
"account_id": "ABC123"
},
"status": "Not Started",
"workflow_id": "11111111-2222-3333-4444-555555555555",
"workflow_version": 3,
"callback": "https://example.com/verification/callback"
}Поддержка KYC и KYB
Один эндпоинт создаёт и сессии Проверки пользователей, и сессии Верификации бизнеса. Тип сценария определяет, какая именно сессия создаётся:- Передайте
workflow_idсценария KYC: создаётся сессия Проверки пользователей (KYC). Ответ содержитsession_kind: "user". - Передайте
workflow_idсценария KYB: создаётся сессия Верификации бизнеса (KYB). Ответ содержитsession_kind: "business".
Примеры
- Проверка пользователей (KYC)
- Верификация бизнеса (KYB)
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "YOUR_KYC_WORKFLOW_ID",
"vendor_data": "user-42",
"callback": "https://yourapp.com/callback"
}'
{
"session_id": "4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a",
"session_kind": "user",
"session_number": 1024,
"session_token": "...",
"url": "https://verify.didit.me/session/...",
"status": "Not Started",
"workflow_id": "YOUR_KYC_WORKFLOW_ID",
"vendor_data": "user-42"
}
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "YOUR_KYB_WORKFLOW_ID",
"vendor_data": "biz-acme-001",
"callback": "https://yourapp.com/callback"
}'
{
"session_id": "bs-01HJX1...",
"session_kind": "business",
"session_number": 89,
"session_token": "...",
"url": "https://verify.didit.me/session/...",
"status": "Not Started",
"workflow_id": "YOUR_KYB_WORKFLOW_ID",
"vendor_data": "biz-acme-001"
}
Документы для электронной подписи
Если в сценарии есть шаг Электронная подпись, который берёт документы из сессии (signature_documents_source имеет значение session или both), передайте их в sign.documents. Каждый документ представляет собой файл в base64, поэтому Didit не нужно загружать его по URL.
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"documents": [
{
"title": "Loan agreement",
"file_name": "loan-agreement.pdf",
"content_base64": "JVBERi0xLjcKJc...",
"fields": [
{ "key": "borrower_signature", "type": "signature", "label": "Borrower signature", "page": 3, "x": 0.1, "y": 0.78, "width": 0.32, "height": 0.06 },
{ "key": "date_signed", "type": "date_signed", "label": "Date", "page": 3, "x": 0.6, "y": 0.8, "width": 0.2, "height": 0.03, "date_format": "DD/MM/YYYY" },
{ "key": "loan_amount", "type": "data", "label": "Loan amount", "page": 1, "x": 0.34, "y": 0.31, "width": 0.3, "height": 0.03, "prefill": "api.loan_amount" },
{ "key": "initials", "type": "initials", "anchor": { "text": "[[initials]]", "occurrence": "all", "offset_x": 0, "offset_y": -0.005, "width": 0.12, "height": 0.04 } }
]
}
],
"field_values": { "loan_amount": "12,000 EUR" }
}
}
| Поле | Правила |
|---|---|
title | Показывается подписанту. От 1 до 255 символов. По умолчанию равно file_name. |
file_name | Обязательно. Оканчивается на .pdf или .docx. От 1 до 255 символов. |
content_base64 | Обязательно. PDF может быть размером до 20 МБ и содержать до 100 страниц, без пароля, скриптов и вложенных файлов. Файл Word может быть размером до 20 МБ; он конвертируется в PDF во время выполнения запроса, не дольше 25 секунд. Затем PDF подчиняется тем же ограничениям. До 5 файлов Word на сессию. |
fields | Необязательно. До 200 полей, которые размещаются в документе, в формате объекта поля без id. Каждое поле требует key и type, а также либо позицию (page, x, y, width и height), либо anchor. role по умолчанию равен подписанту шага, а required и label берутся из типа. Didit задаёт position по месту, где находится поле. Страницы и позиции указываются для PDF или, для файла Word, для сконвертированного PDF. |
fields подписант читает документ и соглашается с ним.
Размещение полей по тексту-якорю
Вместо позиции поле может содержатьanchor: фрагмент текста в документе, который отмечает место поля. Якоря подходят для документов, которые вы формируете для каждой сессии, например из шаблона Word. Для документов сценария размещайте поля в консоли.
Свойство anchor | Правила |
|---|---|
text | От 1 до 64 символов, ищется в тексте документа. Для файла Word: в сконвертированном PDF. |
occurrence | first (по умолчанию) размещает одно поле у первого совпадения. all размещает одно поле у каждого совпадения, а ключам после первого добавляются _2, _3 и так далее. |
offset_x, offset_y | Доли страницы. Левый верхний угол поля определяется как левый верхний угол текста якоря, сдвинутый на эти смещения. |
width, height | Размер поля в долях страницы. |
400 с field_anchor_not_found и ключом поля. Didit не удаляет текст якоря из PDF, поэтому пишите его тем же цветом, что и фон страницы.
Значения полей
sign.field_values задаёт значение каждого поля, у которого prefill равен api.<key>, как для документов сценария, так и для документов сессии. Это объект, ключами которого являются имена <key>. Значения представляют собой строки длиной от 1 до 500 символов для полей text и data и логические значения для checkbox.
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"field_values": { "credit_limit": "3,000 EUR", "monthly_fee": "4.90 EUR" }
}
}
Ошибка (400) | Когда возникает |
|---|---|
field_value_unknown | Ключ, который не используется ни одним полем. |
field_value_missing | Обязательное поле, у которого api.<key> не имеет значения. |
field_value_invalid | Значение, не прошедшее валидацию своего поля. |
Ошибки и повторные вызовы
Сессия принимает до 20 документов и 50 МБ в сумме. Вызов возвращает400 с ошибкой sign, если:
- В сценарии нет шага электронной подписи.
- Вы передали
sign.documents, а шаг принимает только документы сценария. - Шаг принимает только документы сессии, а вы их не передали, или в шаге нет документов сценария, а вы их тоже не передали.
- Документ слишком большой, не является корректным base64 или не относится к поддерживаемому формату.
- Файл Word отклонён с ошибкой
signature_document_not_supportedили не может быть сконвертирован и возвращаетsignature_document_conversion_failed; в обоих случаях указываетсяreasonиз раздела Поддерживаемые файлы. - Поле некорректно, его якорь не найден (
field_anchor_not_found) или значение поля отклонено.
workflow_id и vendor_data возвращает сессию, ожидающую обработки. Если этот вызов содержит sign, его документы, поля и значения полей должны полностью совпадать с первым вызовом (тот же порядок, названия, имена файлов, содержимое, поля и значения). Любое отличие возвращает 400 с {"sign": "signature_document_changed"}: используйте другой vendor_data или дождитесь завершения сессии, ожидающей обработки.
Тестирование со сценариями песочницы
В приложении в режиме песочницы передайтеsandbox_scenario, чтобы заранее задать детерминированный результат (одобрение, конкретный отказ или сценарий «На проверке») без обращения к реальным провайдерам и без списания с баланса:
{
"workflow_id": "YOUR_SANDBOX_WORKFLOW_ID",
"sandbox_scenario": "decline_document_expired"
}
sandbox_scenario отклоняется с ошибкой 400 в продакшн-приложениях. Если на момент создания результат ещё неизвестен, активируйте (или повторно активируйте) его позже через POST /v3/session/{session_id}/sandbox/arm/, пока сессия находится в статусе Not Started: выбор сценария на этапе до начала в размещённом потоке использует тот же эндпоинт. Полный каталог сценариев, реестр магических значений и формат запроса и ответа эндпоинта arm см. в разделе Песочница и тестовые данные.
vendor_data привязывает сессию к сущности
- Для сценариев KYC привязывает к сущности пользователя. Если пользователя не существует, он создаётся автоматически.
- Для сценариев KYB привязывает к сущности компании. Если компания новая, она создаётся автоматически.
Биометрическое согласие в Иллинойсе, Техасе и Колорадо
Хостед-флоу и нативный SDK версии 4.10.0 или новее могут показать явный шаг биометрического согласия перед первым захватом лица. Это зависит от режима согласия приложения и от того, где находится пользователь. На это решение влияют два необязательных поля:user_state: место проживания пользователя, если вы его знаете (US-IL,ILилиIllinois). В режиме Auto штат из списка охваченных заставляет флоу запросить согласие.biometric_consent: объект с полямиgiven_atиtext_versionдля согласия, которое вы уже получили. Флоу повторно не запрашивает согласие.
Важно: уведомление пользователя и получение согласия по-прежнему происходят в вашем продукте
Create Session создаёт URL верификации и токен сессии. Сам по себе он не подтверждает, что вы предоставили пользователю необходимые уведомления или получили согласие, требуемое для вашего конкретного сценария использования.
Если вы запускаете сессию Didit из собственного приложения, веб-сайта, обёртки SDK или White label-флоу, вам следует проработать юридическую часть в собственном UX до того, как пользователь начнёт захват.
Рекомендуемый чек-лист перед верификацией
- Сообщите пользователю, что верификацию запрашивает ваша компания, а флоу обеспечивает провайдер верификации / обработчик данных Didit.
- Добавьте ссылку на вашу политику конфиденциальности и любые юридические условия со стороны контролера данных, которые применяются к этому пути пользователя.
- Добавьте ссылки на Политику конфиденциальности верификации и Пользовательское соглашение для верификации личности от Didit.
- Если ваш флоу включает захват документа, селфи, проверку живости или биометрию, соберите явное утвердительное согласие везде, где этого требует применимое законодательство или ваша правовая позиция.
- Если вы используете собственный UI, собственный домен или путь только через API, предоставьте эту информацию в вашем продукте до того, как отправить пользователя во флоу Didit.
- Если ваша юридическая служба требует журнал аудита, храните собственную запись текста уведомления и согласия, отметку времени и связанные метаданные.
Авторизации
API-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys.
Тело
Постоянный идентификатор сценария, который определяет, какие шаги верификации будут выполнены в сессии. Сценарии создаются и управляются на странице Workflows в консоли. Значение workflow_id также неявно определяет, является ли сессия KYC или KYB.
"11111111-2222-3333-4444-555555555555"
Уникальный идентификатор верифицируемого пользователя, например UUID, адрес электронной почты или внутренний ID пользователя. Это поле используется для: (1) Группировки пользователей — сессии с одинаковым vendor_data связываются с одним профилем пользователя на вкладке Users. (2) Обнаружения дубликатов между сессиями — при проверке на дублирование лиц, документов, номеров телефонов, адресов электронной почты, IP-адресов или цифровых отпечатков устройств сессии с одинаковым vendor_data считаются одним и тем же пользователем и исключаются из совпадений. Без vendor_data каждая сессия рассматривается как отдельный пользователь, и отображаются все потенциальные дубликаты. Мы настоятельно рекомендуем всегда указывать vendor_data, чтобы снизить уровень шума при обнаружении дубликатов.
"user-123"
Необязательная область обнаружения дубликатов внутри вашей организации. Проверки на дубликаты лиц сравнивают эту сессию только с другими сессиями с тем же сегментом, поэтому раздельные базы аккаунтов (личные и корпоративные аккаунты или отдельные базы для B2B-субклиентов) не помечают человека, законно владеющего по одному аккаунту в каждой из них. Опустите это поле, чтобы использовать единую область по умолчанию, применяемую сегодня ко всем сессиям. Сопоставление со списком блокировки и белым списком игнорирует это поле.
64"business-accounts"
URL для перенаправления пользователя после завершения верификации. Didit автоматически добавляет verificationSessionId и status (Approved, Declined, In Review) в качестве query-параметров. Пользовательские схемы URL (например, myapp://) поддерживаются для мобильных обратных вызовов. Если параметр опущен, используется callback_url сценария по умолчанию. Если у приложения настроены разрешённые домены (allowed_domains в PATCH /v3/webhook/), обратный вызов http или https должен относиться к одному из этих источников (та же схема, хост и порт), иначе запрос вернёт ошибку 400 по полю callback: callback must be on one of the application's allowed domains: https://app.example.com. Пользовательские схемы URL принимаются всегда.
"https://example.com/verification/callback"
Определяет, какое устройство должно обработать перенаправление на указанный URL обратного вызова. Используйте initiator, чтобы перенаправить только устройство, начавшее процесс, completer для устройства, завершившего его, или both, чтобы разрешить запуск обратного вызова любому из устройств. Если вы заметите, что обратный вызов срабатывает нестабильно, мы рекомендуем установить это значение в both.
initiator, completer, both "both"
Произвольный JSON, сохранённый с сессией и возвращаемый в ответе и событиях webhook. Допускается любое JSON-значение (объект, строка, число, массив), но рекомендуется JSON-объект с парами ключ/значение. Не отображается конечному пользователю. Используйте его для передачи собственных корреляционных ID, вариантов A/B-тестирования или контекста компании.
{
"user_type": "premium",
"account_id": "ABC123"
}
Теги, добавляемые к сессии при ее создании, по имени. До 10, каждый длиной до 50 символов. Имена нечувствительны к регистру и сохраняются в верхнем регистре. Имя, которого еще нет в приложении, создается как новый тег. Теги отображаются на сессии в консоли, где по ним можно фильтровать.
1050["VIP", "ONBOARDING Q4"]
Код языка (ISO 639-1) для интерфейса процесса верификации. Определяет язык, отображаемый конечному пользователю во время верификации. Если не указан, язык браузера определяется автоматически. Ознакомиться со всеми поддерживаемыми языками можно здесь.
en, ar, bg, bn, bs, ca, cnr, cs, da, de, el, es, et, fa, fi, fr, he, hi, hr, hu, hy, id, it, ja, ka, kk, ko, ky, lt, lv, mk, mn, ms, nl, no, pl, pt-BR, pt, ro, ru, sk, sl, so, sq, sr, sv, th, tr, uk, uz, vi, zh-CN, zh-TW, zh "en"
Контактная информация пользователя, которая может использоваться для уведомлений, автозаполнения форм верификации и проверки телефона. Включает адрес электронной почты, предпочтительный язык для сообщений и номер телефона.
Show child attributes
Show child attributes
{
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
}
Ожидаемые данные пользователя, используемые для перекрёстной проверки с данными, извлечёнными из документа, удостоверяющего личность пользователя, подтверждения адреса и других шагов верификации. Несоответствия отображаются как предупреждения в решении; некоторые поля (например, id_country, expected_document_types) также изменяют сценарий для пользователя. Для сценариев верификации бизнеса (KYB) используются только поля компании (company_name, registry_country, registration_number) — они предварительно заполняют поиск в реестре компаний для пользователя, а все поля физических лиц игнорируются.
Show child attributes
Show child attributes
{
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
Портретное изображение лица конечного пользователя в кодировке Base64 (не более 2 МБ; JPEG, PNG, WebP или TIFF). Используется в качестве эталонного изображения для сопоставления со снимком проверки живости, если используется сценарий Biometric Authentication с включённым Сравнением лиц или любой граф-сценарий, где Сравнение лиц выполняется до Верификации личности (OCR). Необязательно, если у пользователя из vendor_data уже есть сохранённое изображение лица: Didit повторно использует его автоматически, выбирая в порядке приоритета: лицо из одобренной проверки живости, фото с чипа биометрического паспорта, портрет из документа, удостоверяющего личность, лицо профиля, добавленное вручную (повторно используются только лица из одобренных сессий или лица, добавленные вами самостоятельно). При передаче portrait_image всегда имеет приоритет над сохранённым лицом. Если параметр опущен и сохранённое лицо отсутствует (или vendor_data не отправлен), создание сессии завершается ошибкой 400. Игнорируется для других типов сценариев.
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
Слаг сценария только для песочницы. Принимается только в том случае, если API-ключ принадлежит приложению в режиме песочницы; для продакшн-приложений отклоняется. Если задан, процесс создания разворачивает встроенные магические значения сценария во входные поля сессии (contact_details, expected_details), чтобы мок-провайдеры воспроизводили результат сценария через реальный конвейер сценария верификации. Каталог сценариев см. в GET /v1/sandbox/scenarios/ или в разделе Песочница и тестовые данные. Вы также можете активировать (или повторно активировать) сценарий после создания с помощью POST /v3/session/{sessionId}/sandbox/arm/, пока сессия всё ещё находится в статусе Not Started. Для проверок без документов используйте lookup_partial_match, lookup_no_match или lookup_provider_error, чтобы протестировать настроенный лимит попыток и резервный вариант. Для кошельков идентификации используйте wallet_cancelled, wallet_timeout или wallet_provider_error; значение approve имитирует верифицированный кошелёк. Все кошельки из каталога можно тестировать в песочнице, включая схемы, недоступные в продакшн-приложениях. Плата за имитированные попытки не взимается.
"decline_document_expired"
Входные данные электронной подписи для этой сессии. documents содержит документы для подписания для сценария, шаг электронной подписи которого берёт документы из сессии (signature_documents_source со значением session или both): до 20 документов и 50 MB суммарно. field_values заполняет поля, у которых prefill имеет значение api.<key>, как в документах сценария, так и в документах сессии. Повторное создание сессии с теми же workflow_id и vendor_data возвращает ожидающую сессию; если этот вызов передаёт sign, его документы, поля и значения должны быть идентичны исходным, а любые отличия возвращают 400 с {"sign": "signature_document_changed"}. См. Документы электронной подписи.
Show child attributes
Show child attributes
Место проживания лица, если оно известно: код подразделения ISO 3166-2 (US-IL, ES-M) либо код или название штата США (IL, Illinois). Если законодательство штата требует явного согласия на обработку биометрии (Иллинойс, Техас, Колорадо), сценарий верификации запрашивает его перед захватом лица с триггером declared_state. Нераспознанное значение возвращает 400. См. раздел Согласие на обработку биометрии.
16"US-IL"
Явное биометрическое согласие, которое вы уже получили от человека. Оно удовлетворяет требованию, поэтому в процессе верификации повторный запрос не выполняется, а в решении оно фиксируется со статусом status: "given" и триггером customer_collected. Ответ, который пользователь уже дал в процессе, никогда не перезаписывается. См. Биометрическое согласие.
Show child attributes
Show child attributes
Ответ
Сессия создана (или возвращена, если незавершённая сессия с теми же vendor_data уже существует в последней опубликованной версии сценария). Ответ содержит сериализованную сессию, включая url размещённой страницы верификации для перенаправления пользователя.
Уникальный идентификатор сессии верификации. Используйте этот id при вызове GET /v3/session/{sessionId}/decision/.
"11111111-2222-3333-4444-555555555555"
Порядковый, удобный для восприятия номер, присвоенный сессии внутри вашего приложения. Полезен для службы поддержки и панелей управления.
43762
12-символьный URL-безопасный token, который авторизует конечного пользователя для доступа к размещённому сценарию верификации по адресу url. Действителен до тех пор, пока сессия не истекла. Относитесь к нему как к секрету: любой, у кого он есть, может открыть сценарий верификации для этой сессии.
"3FaJ9wLqX2Mz"
Размещённый URL верификации, на который перенаправляется конечный пользователь. URL содержит session_token и, если настроено, использует ваш White label домен. Если запрос содержит language, URL включает языковой сегмент пути — https://verify.didit.me/{language}/session/{session_token} (например, /es/session/...); без language этот сегмент опускается.
"https://verify.didit.me/session/3FaJ9wLqX2Mz"
Идентификатор, переданный вами в запросе для привязки сессии к пользователю или компании в вашей собственной системе. Возвращается без изменений. Null, если не указан.
"user-123"
Произвольный JSON payload, сохранённый с сессией при её создании. Возвращается в неизменном виде — любое переданное JSON-значение (объект, строка, число, массив) возвращается как есть, хотя рекомендуется передавать JSON-объект. Не отображается конечному пользователю. Всегда присутствует в ответах; null, если не было передано при создании.
{
"user_type": "premium",
"account_id": "ABC123"
}
Текущий статус сессии. Для только что созданных сессий возвращается Not Started. Если для тех же данных vendor_data в последней опубликованной версии сценария уже существовала незавершённая сессия, возвращаемый статус отражает состояние этой существующей сессии.
Not Started, In Progress, Approved, Declined, In Review, Expired, Abandoned, Kyc Expired, Resubmitted, Awaiting User "Not Started"
Финальный URL перенаправления, на который направляется пользователь после завершения сценария. Didit добавляет к этому URL ?verificationSessionId={session_id}&status={status}. По умолчанию используется настроенный URL обратного вызова сценария, если он не передан в запросе; null, если ни один из них не задан. Если в приложении настроены разрешённые домены и данный URL является веб-URL вне их списка (например, значение по умолчанию в сценарии, заданное до изменения списка), размещённый сценарий не перенаправляет пользователя на него.
"https://example.com/verification/callback"
Постоянный идентификатор сценария, в рамках которого выполняется эта сессия. Всегда является постоянным идентификатором группы сценария — даже если в запросе был указан UUID конкретной версии сценария (для обратной совместимости), ответ содержит постоянный workflow_id. Используйте его для сопоставления сессии со сценарием, настроенным вами в консоли.
"11111111-2222-3333-4444-555555555555"
Номер опубликованной версии сценария, к которой сессия была привязана при создании. Didit сопоставляет workflow_id с последней опубликованной версией сценария на момент создания сессии, и сессия продолжает выполняться на этой версии, даже если сценарий позже будет опубликован повторно.
3
Теги сессии, по именам.
["VIP", "ONBOARDING Q4"]