> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# KYB इंटीग्रेशन गाइड: आर्किटेक्चर और पैटर्न

> Didit से KYB इंटीग्रेशन: आर्किटेक्चर, सत्र, होस्टेड फ़्लो, webhooks और निर्णय। $2.00 प्रति जाँच से, देश और स्तर के अनुसार मूल्य।



KYB इंटीग्रेशन प्रॉम्प्ट
        प्रॉम्प्ट को क्लिपबोर्ड पर कॉपी करें



      
      

\<pre>

\````# Goal — ship a production-ready KYB (business verification) integration

KYB runs through the same `/v3/session/` endpoint as KYC. The session's workflow determines whether it's a KYC or KYB session — pass a KYB workflow id and Didit creates a business session automatically (`session_kind: "business"`).

\## End-to-end flow

\```
You: POST /v3/session/ (KYB workflow_id, vendor_data) → session_id, url, session_token
You: deliver url to the business contact (email / your UI / iframe)
Biz: completes the hosted flow (registry confirm → Key People → documents → AML)
Didit → Webhook: status.updated with session_kind: "business"
You: GET /v3/session/{session_id}/decision/ → full KYB decision
You: branch on decision.status ("Approved" / "Declined" / "In Review" / "Resubmitted")
\```

\## Create a KYB session

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "$KYB_WORKFLOW_ID",
"vendor_data": "biz-acme",
"callback": "https://myapp.com/kyb/return",
"metadata": {"plan": "growth", "country": "GBR"}
}'
\```

Recommended fields:

\- `workflow_id` — references your KYB workflow.
\- `vendor_data` — your business id; binds the session to a [Business entity](/entities/businesses/overview).
\- `callback` — where to redirect the user after completion.
\- `metadata` — JSON attached to the session for your own reporting.

\## Webhook events for KYB

\| Event | Trigger |
\|---|---|
\| `status.updated` (with `session_kind === "business"`) | KYB session status changed. Follow this event for progress. |
\| `data.updated` (with `session_kind === "business"`) | A reviewer edited registry data or Key People in the console, or the registry reported a change (registry monitoring). Not sent for document uploads or Key People submissions. |
\| `business.status.updated` | Linked Business entity status changed |
\| `business.data.updated` | Linked Business entity profile / counters changed |

Subscribe via `POST /v3/webhook/destinations/` with `webhook_version: "v3"`. Verify the `X-Signature-V2` header (HMAC-SHA256 of canonical JSON). De-dupe on `event_id`. Respond within 5 seconds.

\## KYB decision shape (V3 plural arrays)

\```bash
curl https://verification.didit.me/v3/session/$SESSION_ID/decision/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

Key V3 arrays you'll iterate:

\| Array | Holds |
\|---|---|
\| `key_people_checks[]` | UBOs, shareholders, directors, officers — bucketed into `registry` (from the registry lookup) and `submitted` (what the business confirmed). Plus a `ubo_kyc_summary` rollup. |
\| `document_verifications[]` | Each item has `status`, `node_id`, `items[]` (signed `file_url` + OCR extract), `groups`, `required_groups`. |
\| `aml_screenings[]` | Company AML and per-person AML hits. |

The KYB-specific features are `KYB_REGISTRY`, `AML`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`. Statuses are the exact labels `"Not Finished"`, `"Approved"`, `"Declined"`, `"In Review"`, `"Resub Requested"`.

\## Apply-decision logic

\```ts
switch (decision.status) {
case "Approved":   await onboardBusiness(decision); break;
case "Declined":   await logRejection(collectWarnings(decision), decision); break; // warnings[] tags on each feature array
case "In Review":  await markPending(decision); break; // wait for next webhook
case "Resubmitted":await notifyBusiness(decision); break; // business needs to re-upload
case "Awaiting User": await pingChildPersonForKyc(decision); break; // child Key People KYC pending
}
\```

See /business-verification/statuses for the full state machine.

\## Resubmission flow

When a session transitions to `Resubmitted` (or a feature to `Resub Requested`, or a feature is marked for resubmission), re-deliver the same `url` — the hosted flow resumes at the resubmission step. To re-verify a specific Key Person, resubmit that person's child KYC session; the parent `kyb_key_people` re-aggregates automatically.

\## Key People child KYC

If your KYB workflow has KYC required for some roles, each person triggers a child KYC session automatically. While any child is in progress, the parent's `kyb_key_people` status is `Awaiting User`. Configure per-role required/skippable behaviour at *Workflows → [KYB workflow] → Key People*. A child session expires after the session expiration time of the KYC workflow its role is mapped to, not the KYB session's. A party whose session was deleted, or whose link expired before the person started it, is reissued with `POST /v3/session/{session_id}/kyb/parties/{party_uuid}/regenerate/`.

\## Failure modes

\| Scenario | Response |
\|---|---|
\| Invalid `workflow_id` | `400 Bad Request` |
\| Wrong workflow type (KYC instead of KYB) | Session is created but runs KYC steps — verify the workflow's `workflow_type` is `"kyb"` |
\| Duplicate `vendor_data` | A new session is created — that's by design for re-KYB |
\| Company country outside the workflow's allowed countries | The registry check raises the `KYB_COUNTRY_RESTRICTED` warning |
\| Registry provider outage during company search | `502` with `code: "kyb_registry_provider_unavailable"`. Not billed. In Didit's hosted flow, the business is automatically offered manual company entry instead of a retry-only error. |
\| Rate limit | `429` with `Retry-After` header |

\## Sources of truth

\- /sessions-api/create-session — request body schema
\- /business-verification/response-schema — KYB decision payload
\- /business-verification/statuses — feature state machine
\- /business-verification/webhooks — KYB-specific event catalog
\- /entities/businesses/data-model — Business entity schema
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

यहाँ पेस्ट करें

यह गाइड [क्विकस्टार्ट](https://docs.didit.me/hi/business-verification/quickstart.md) की पूरक है। इसमें आर्किटेक्चर, हर इंटीग्रेशन निर्णय, और वे ऑपरेशनल पैटर्न शामिल हैं जो प्रोडक्शन में KYB को भरोसेमंद बनाते हैं।## आर्किटेक्चर```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Biz as Business contact
    participant Webhook as Your webhook endpoint

    You->>Didit: POST /v3/session/ (workflow_id, vendor_data)
    Didit-->>You: session_id, url, token
    You->>Biz: Deliver hosted verification URL (your email/flow)
    Biz->>Didit: Completes KYB hosted flow
    Didit->>Didit: Registry lookup, AML screening, OCR
    Didit->>Webhook: status.updated (session_kind: business)
    You->>Didit: GET /v3/session/{id}/decision/
    Didit-->>You: Full KYB decision payload
    You->>You: Onboard / reject / escalate based on status
```## प्रमाणीकरणसभी अनुरोधों के लिए आपकी एप्लिकेशन की API कुंजी वाला `x-api-key` हेडर आवश्यक है। कुंजी रोटेशन, एनवायरनमेंट अलगाव और स्कोप के बारे में जानने के लिए [API प्रमाणीकरण](https://docs.didit.me/hi/getting-started/api-authentication.md) देखें।## सत्र निर्माणएकमात्र endpoint: `POST /v3/session/`। वर्कफ़्लो का प्रकार तय करता है कि सत्र KYC है या KYB, इसके लिए किसी स्पष्ट "business" फ़्लैग की ज़रूरत नहीं है।**सत्र बनाते समय अनुशंसित फ़ील्ड:**| फ़ील्ड | उद्देश्य |
| - | - |
| `workflow_id` | आवश्यक: आपके KYB वर्कफ़्लो का संदर्भ देता है। |
| `vendor_data` | व्यवसाय के लिए आपका पहचानकर्ता। सत्र को [Business entity](https://docs.didit.me/hi/entities/businesses/overview.md) से जोड़ता है। |
| `callback_url` | वैकल्पिक: पूरा होने के बाद उपयोगकर्ता को कहाँ रीडायरेक्ट करना है। |
| `expected_details` | वैकल्पिक: `{ company_name, registry_country, registration_number }`। कंपनी रजिस्ट्री खोज को पहले से भरता है: निगमन का देश पहले से चुना और लॉक होता है (`registry_country` को `XX` के रूप में, या राज्य-स्तरीय रजिस्ट्री के लिए `XX-YY`, जैसे `US-CA`), कंपनी का नाम और पंजीकरण संख्या वाले फ़ील्ड पहले से भरे जाते हैं, और दिए गए विवरण पर खोज अपने आप चलती है, जिसमें दोनों पहचानकर्ता होने पर दोनों को मिलाया जाता है। केवल प्रीफ़िल है, मेल न खाने पर चेतावनी नहीं आती। |
| `metadata` | वैकल्पिक: सत्र से जुड़ा JSON। |पूरा स्कीमा: [सत्र बनाएँ](https://docs.didit.me/hi/sessions-api/create-session.md)।## होस्टेड लिंक भेजनारिस्पॉन्स का `url` एक होस्टेड सत्यापन लिंक है। इसे भेजने के विकल्प:- इसे अपने प्लेटफ़ॉर्म से ईमेल करें।
- इसे अपने ऑनबोर्डिंग UI में लिंक के रूप में एम्बेड करें।
- इसे इन-ऐप वेबव्यू (iOS / Android / React Native) में खोलें।आप [व्हाइट लेबल](https://docs.didit.me/hi/console/white-label.md) के ज़रिए होस्टेड अनुभव को **अनुकूलित** कर सकते हैं: लोगो, रंग, डोमेन और ईमेल टेम्पलेट।## पोलिंग बनाम webhooksWebhooks अनुशंसित पैटर्न हैं। प्रोसेसिंग पूरी होते ही Didit पूर्णता के इवेंट आपके सब्सक्राइब किए गए endpoint पर POST करता है।पोलिंग विकास के लिए, या तब समर्थित है जब आपका webhook endpoint पहुँच योग्य न हो:* `GET /v3/session/{id}/decision/` पर पोल करें, शुरू में हर 10 सेकंड, अधिकतम 60 सेकंड तक एक्सपोनेंशियल बैकऑफ़ के साथ।
* जब `status` इनमें से कोई हो: `"Approved"`, `"Declined"`, `"In Review"`, तब पोलिंग रोकें।> [!WARNING]
>
> बहुत अधिक आवृत्ति पर पोलिंग [रेट लिमिट](https://docs.didit.me/hi/integration/rate-limiting.md) तक पहुँच सकती है। प्रोडक्शन में हमेशा webhooks को प्राथमिकता दें।## Webhook हैंडलिंगउन इवेंट्स की सदस्यता लें जिनकी आपको परवाह है। वही इवेंट KYC और KYB दोनों को कवर करते हैं, और व्यवसाय-सत्र इवेंट पहचानने के लिए payload के भीतर `session_kind: "business"` होता है:- `status.updated`: सत्र की स्थिति बदली। KYB सत्रों के लिए `session_kind === "business"` पर फ़िल्टर करें।
- `data.updated`: किसी समीक्षक ने कंसोल में रजिस्ट्री डेटा या Key People संपादित किया, या रजिस्ट्री ने कोई बदलाव रिपोर्ट किया। जब आवेदक दस्तावेज़ अपलोड करता है या Key People सबमिट करता है, तब यह नहीं भेजा जाता: उसके लिए `status.updated` का अनुसरण करें। वही `session_kind` फ़िल्टर लागू होता है।
- `business.status.updated` / `business.data.updated`: लिंक की गई [Business entity](https://docs.didit.me/hi/entities/businesses/overview.md) में बदलाव हुआ।इवेंट की पूरी सूची: [KYB webhooks](https://docs.didit.me/hi/business-verification/webhooks.md)। सिग्नेचर सत्यापन और पुनः प्रयास के नियम: [webhooks reference](https://docs.didit.me/hi/integration/webhooks.md)।## निर्णयों को संभालना```typescript theme={null}
switch (decision.status) {
  case 'Approved':
    await onboardBusiness(decision);
    break;
  case 'Declined':
    // The KYB decision has no single reason code: collectWarnings is your helper
    // that flattens warnings[] from registry_checks, document_verifications,
    // key_people_checks and aml_screenings
    await logRejection(collectWarnings(decision), decision);
    break;
  case 'In Review':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'Resubmitted':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}
```पूरी स्टेट मशीन के लिए [KYB स्थितियाँ](https://docs.didit.me/hi/business-verification/statuses.md) देखें, और निर्णय को समझाने वाले टैग के लिए [KYB चेतावनियाँ](https://docs.didit.me/hi/business-verification/warnings.md)।## पुनः सबमिशन फ़्लोजब कोई Business Verification (KYB) सत्र `Resubmitted` में बदलता है (या कोई सुविधा पुनः सबमिशन के लिए चिह्नित होती है), तो व्यवसाय को सुधारा हुआ या अतिरिक्त डेटा अपलोड करना होता है।आप यह कर सकते हैं:- **उसी `url` को फिर से भेजें**: होस्टेड फ़्लो वहीं से आगे बढ़ता है जहाँ पुनः सबमिशन की ज़रूरत है।
- **निष्क्रिय key-person लिंक फिर से जारी करें**: जिस पक्ष का चाइल्ड KYC सत्र हटाया गया था, या जिसका सत्र उस व्यक्ति द्वारा शुरू किए जाने से पहले समय-सीमा समाप्त हो गया था, उसे [Regenerate Key People KYC Session](https://docs.didit.me/hi/sessions-api/regenerate-kyb-party.md) से नया सत्र मिलता है।
- **Business Console में एक [केस](https://docs.didit.me/hi/transaction-monitoring/cases.md) खोलें** ताकि आंतरिक रूप से आदान-प्रदान ट्रैक किया जा सके।## अपने फ़्रंट एंड से चरण चलाएँदस्तावेज़ और Key People चरण आपके सर्वर से भी आपकी API कुंजी के साथ चलाए जा सकते हैं, ताकि उपयोगकर्ता इंटरफ़ेस आपके पास रहे और सत्यापन तथा निर्णय Didit के पास। हर कॉल KYB सत्र तक सीमित होती है, उसके लिए `write:businesses` अनुमति चाहिए (निकाले गए पक्ष पढ़ने के लिए `read:businesses` या `read:sessions` भी स्वीकार्य हैं), और वही जाँच, बिलिंग और चरण आगे बढ़ाने का काम चलाती है जो होस्टेड पेज करता है।1) जब सत्र KYB Documents चरण पर हो, तब [कॉर्पोरेट दस्तावेज़ अपलोड करें](https://docs.didit.me/hi/sessions-api/kyb-upload-documents.md)।
2) [दस्तावेज़ों में उल्लिखित पक्षों को पढ़ें](https://docs.didit.me/hi/sessions-api/kyb-extracted-parties.md), जिसमें शेयरधारक और स्वामित्व प्रतिशत शामिल हैं, और उन्हें अपने आवेदक को दिखाएँ।
3) [पक्ष ड्राफ़्ट](https://docs.didit.me/hi/sessions-api/kyb-list-party-drafts.md) [बनाएँ](https://docs.didit.me/hi/sessions-api/kyb-create-party-draft.md), [संपादित करें](https://docs.didit.me/hi/sessions-api/kyb-update-party-draft.md) और [हटाएँ](https://docs.didit.me/hi/sessions-api/kyb-delete-party-draft.md)। ड्राफ़्ट घोषित नहीं होता और उसकी कोई लागत नहीं है।
4) [ड्राफ़्ट सबमिट करें](https://docs.didit.me/hi/sessions-api/kyb-submit-parties.md)। Didit तय करता है कि किन पक्षों का सत्यापन ज़रूरी है, हर एक के लिए KYC सत्र बनाता है, और उसका `kyc_session_url` लौटाता है ताकि आप उसे भेज सकें या एम्बेड कर सकें।
5) होस्टेड फ़्लो की तरह, सत्र से एकीकृत निर्णय पढ़ें।जब सत्र किसी दूसरे चरण पर हो, तब की गई कॉल `409 kyb_step_mismatch` लौटाती है, जिसमें वह चरण दिया जाता है जिस पर सत्र है। समाप्त सत्र पर `409 kyb_session_not_writable` मिलता है।## व्यवसाय प्रोफ़ाइल एकत्रीकरणअगर सत्र बनाते समय `vendor_data` पास करते हैं, तो Didit उस व्यवसाय के सभी सत्रों को एक ही [Business entity](https://docs.didit.me/hi/entities/businesses/overview.md) में एकत्र करता है। यह जानने के लिए कि "क्या यह व्यवसाय अभी पूरी तरह सत्यापित है?", सत्रों को दोबारा देखे बिना इकाई के `features` मैप का उपयोग करें।लाभ:- आवधिक re-KYB फ़्लो उसी प्रोफ़ाइल में जुड़ते हैं।
- उसी `vendor_data` के साथ मॉनिटर किए गए लेन-देन में व्यवसाय का जोखिम संदर्भ होता है।
- User entities से जुड़े UBO और अधिकारी इकाइयों के बीच संबंध भरते हैं।## सर्वोत्तम अभ्यास| अभ्यास | कारण |
| - | - |
| हमेशा `vendor_data` पास करें | इसके बिना सत्र अनाथ हो जाता है और उसे एकत्रित नहीं किया जा सकता। |
| पोलिंग के बजाय webhook का उपयोग करें | कम विलंबता, और रेट लिमिट पर कोई दबाव नहीं। |
| webhook हस्ताक्षरों को सत्यापित करें | स्पूफ किए गए webhook इवेंट को रोकते हैं। |
| अपनी ओर `session_id` स्टोर करें | निर्णय प्राप्त करने और PDF बनाने के लिए इसकी आवश्यकता होती है। |
| सत्रों को `metadata` से टैग करें | रिपोर्टिंग और डीबगिंग आसान बनाता है। |
| परीक्षण वर्कफ़्लो सेट अप करें | प्रोडक्शन से पहले इंटीग्रेशन टेस्टिंग के लिए सैंडबॉक्स वर्कफ़्लो का उपयोग करें। |## त्रुटि प्रबंधन| परिदृश्य | रिस्पॉन्स |
| - | - |
| अमान्य `workflow_id` | `400 Bad Request` |
| समान `vendor_data` वाला डुप्लिकेट सत्र | नया सत्र बनता है। यह जानबूझकर किया गया है, क्योंकि पुनः सत्यापन अपेक्षित है। |
| कंपनी का देश वर्कफ़्लो के अनुमत देशों से बाहर | रजिस्ट्री जाँच `KYB_COUNTRY_RESTRICTED` चेतावनी उत्पन्न करती है। |
| कंपनी की खोज के दौरान रजिस्ट्री प्रदाता की सेवा बाधित होना | `POST /v3/kyb/search/` `502` लौटाता है, जिसमें `code: "kyb_registry_provider_unavailable"` होता है। शुल्क नहीं लगता। पुनः प्रयास करें, या `code` के आधार पर मैन्युअल कंपनी प्रविष्टि का विकल्प दें। Didit के होस्टेड फ़्लो में, केवल पुनः प्रयास वाली त्रुटि के बजाय व्यवसाय को स्वचालित रूप से मैन्युअल प्रविष्टि में भेजा जाता है। देखें [KYB रजिस्ट्री खोज](https://docs.didit.me/hi/standalone-apis/kyb-registry-search.md#रजिस्ट्री-आउटेज-को-संभालना)। |
| रेट लिमिट | `Retry-After` हेडर के साथ `429 Too Many Requests`। |[रेट लिमिटिंग](https://docs.didit.me/hi/integration/rate-limiting.md) का पूरा संदर्भ।## अगले चरण> [card] [webhook](https://docs.didit.me/hi/business-verification/webhooks.md)
>
> हर KYB इवेंट और payload।> [card] [स्टेटस](https://docs.didit.me/hi/business-verification/statuses.md)
>
> स्टेट मशीन का संदर्भ।> [card] [रिस्पॉन्स स्कीमा](https://docs.didit.me/hi/business-verification/response-schema.md)
>
> KYB निर्णय को डिकोड करना।


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.