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

यह गाइड क्विकस्टार्ट की पूरक है। इसमें आर्किटेक्चर, हर इंटीग्रेशन निर्णय, और वे ऑपरेशनल पैटर्न शामिल हैं जो प्रोडक्शन में KYB को भरोसेमंद बनाते हैं।

आर्किटेक्चर

प्रमाणीकरण

सभी अनुरोधों के लिए आपकी एप्लिकेशन की API कुंजी वाला x-api-key हेडर आवश्यक है। कुंजी रोटेशन, एनवायरनमेंट अलगाव और स्कोप के बारे में जानने के लिए API प्रमाणीकरण देखें।

सत्र निर्माण

एकमात्र endpoint: POST /v3/session/। वर्कफ़्लो का प्रकार तय करता है कि सत्र KYC है या KYB, इसके लिए किसी स्पष्ट “business” फ़्लैग की ज़रूरत नहीं है। सत्र बनाते समय अनुशंसित फ़ील्ड:

फ़ील्ड	उद्देश्य
`workflow_id`	आवश्यक: आपके KYB वर्कफ़्लो का संदर्भ देता है।
`vendor_data`	व्यवसाय के लिए आपका पहचानकर्ता। सत्र को Business entity से जोड़ता है।
`callback_url`	वैकल्पिक: पूरा होने के बाद उपयोगकर्ता को कहाँ रीडायरेक्ट करना है।
`expected_details`	वैकल्पिक: `{ company_name, registry_country, registration_number }`। कंपनी रजिस्ट्री खोज को पहले से भरता है: निगमन का देश पहले से चुना और लॉक होता है (`registry_country` को `XX` के रूप में, या राज्य-स्तरीय रजिस्ट्री के लिए `XX-YY`, जैसे `US-CA`), कंपनी का नाम और पंजीकरण संख्या वाले फ़ील्ड पहले से भरे जाते हैं, और दिए गए विवरण पर खोज अपने आप चलती है, जिसमें दोनों पहचानकर्ता होने पर दोनों को मिलाया जाता है। केवल प्रीफ़िल है, मेल न खाने पर चेतावनी नहीं आती।
`metadata`	वैकल्पिक: सत्र से जुड़ा JSON।

पूरा स्कीमा: सत्र बनाएँ।

होस्टेड लिंक भेजना

रिस्पॉन्स का url एक होस्टेड सत्यापन लिंक है। इसे भेजने के विकल्प:

इसे अपने प्लेटफ़ॉर्म से ईमेल करें।
इसे अपने ऑनबोर्डिंग UI में लिंक के रूप में एम्बेड करें।
इसे इन-ऐप वेबव्यू (iOS / Android / React Native) में खोलें।

आप व्हाइट लेबल के ज़रिए होस्टेड अनुभव को अनुकूलित कर सकते हैं: लोगो, रंग, डोमेन और ईमेल टेम्पलेट।

पोलिंग बनाम webhooks

Webhooks अनुशंसित पैटर्न हैं। प्रोसेसिंग पूरी होते ही Didit पूर्णता के इवेंट आपके सब्सक्राइब किए गए endpoint पर POST करता है। पोलिंग विकास के लिए, या तब समर्थित है जब आपका webhook endpoint पहुँच योग्य न हो:

GET /v3/session/{id}/decision/ पर पोल करें, शुरू में हर 10 सेकंड, अधिकतम 60 सेकंड तक एक्सपोनेंशियल बैकऑफ़ के साथ।
जब status इनमें से कोई हो: "Approved", "Declined", "In Review", तब पोलिंग रोकें।

बहुत अधिक आवृत्ति पर पोलिंग रेट लिमिट तक पहुँच सकती है। प्रोडक्शन में हमेशा 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 में बदलाव हुआ।

इवेंट की पूरी सूची: KYB webhooks। सिग्नेचर सत्यापन और पुनः प्रयास के नियम: webhooks reference।

निर्णयों को संभालना

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 स्थितियाँ देखें, और निर्णय को समझाने वाले टैग के लिए KYB चेतावनियाँ।

पुनः सबमिशन फ़्लो

जब कोई Business Verification (KYB) सत्र Resubmitted में बदलता है (या कोई सुविधा पुनः सबमिशन के लिए चिह्नित होती है), तो व्यवसाय को सुधारा हुआ या अतिरिक्त डेटा अपलोड करना होता है। आप यह कर सकते हैं:

उसी url को फिर से भेजें: होस्टेड फ़्लो वहीं से आगे बढ़ता है जहाँ पुनः सबमिशन की ज़रूरत है।
निष्क्रिय key-person लिंक फिर से जारी करें: जिस पक्ष का चाइल्ड KYC सत्र हटाया गया था, या जिसका सत्र उस व्यक्ति द्वारा शुरू किए जाने से पहले समय-सीमा समाप्त हो गया था, उसे Regenerate Key People KYC Session से नया सत्र मिलता है।
Business Console में एक केस खोलें ताकि आंतरिक रूप से आदान-प्रदान ट्रैक किया जा सके।

अपने फ़्रंट एंड से चरण चलाएँ

दस्तावेज़ और Key People चरण आपके सर्वर से भी आपकी API कुंजी के साथ चलाए जा सकते हैं, ताकि उपयोगकर्ता इंटरफ़ेस आपके पास रहे और सत्यापन तथा निर्णय Didit के पास। हर कॉल KYB सत्र तक सीमित होती है, उसके लिए write:businesses अनुमति चाहिए (निकाले गए पक्ष पढ़ने के लिए read:businesses या read:sessions भी स्वीकार्य हैं), और वही जाँच, बिलिंग और चरण आगे बढ़ाने का काम चलाती है जो होस्टेड पेज करता है।

जब सत्र KYB Documents चरण पर हो, तब कॉर्पोरेट दस्तावेज़ अपलोड करें।
दस्तावेज़ों में उल्लिखित पक्षों को पढ़ें, जिसमें शेयरधारक और स्वामित्व प्रतिशत शामिल हैं, और उन्हें अपने आवेदक को दिखाएँ।
पक्ष ड्राफ़्ट बनाएँ, संपादित करें और हटाएँ। ड्राफ़्ट घोषित नहीं होता और उसकी कोई लागत नहीं है।
ड्राफ़्ट सबमिट करें। Didit तय करता है कि किन पक्षों का सत्यापन ज़रूरी है, हर एक के लिए KYC सत्र बनाता है, और उसका kyc_session_url लौटाता है ताकि आप उसे भेज सकें या एम्बेड कर सकें।
होस्टेड फ़्लो की तरह, सत्र से एकीकृत निर्णय पढ़ें।

जब सत्र किसी दूसरे चरण पर हो, तब की गई कॉल 409 kyb_step_mismatch लौटाती है, जिसमें वह चरण दिया जाता है जिस पर सत्र है। समाप्त सत्र पर 409 kyb_session_not_writable मिलता है।

व्यवसाय प्रोफ़ाइल एकत्रीकरण

अगर सत्र बनाते समय vendor_data पास करते हैं, तो Didit उस व्यवसाय के सभी सत्रों को एक ही Business entity में एकत्र करता है। यह जानने के लिए कि “क्या यह व्यवसाय अभी पूरी तरह सत्यापित है?”, सत्रों को दोबारा देखे बिना इकाई के 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 रजिस्ट्री खोज।
रेट लिमिट	`Retry-After` हेडर के साथ `429 Too Many Requests`।

रेट लिमिटिंग का पूरा संदर्भ।

अगले चरण

webhook

हर KYB इवेंट और payload।

स्टेटस

स्टेट मशीन का संदर्भ।

रिस्पॉन्स स्कीमा

KYB निर्णय को डिकोड करना।

शुरुआत करें

सुविधाएँ

व्यवसाय प्रोफ़ाइल

संदर्भ

कंसोल

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

आर्किटेक्चर

प्रमाणीकरण

सत्र निर्माण

होस्टेड लिंक भेजना

पोलिंग बनाम webhooks

Webhook हैंडलिंग

निर्णयों को संभालना

पुनः सबमिशन फ़्लो

अपने फ़्रंट एंड से चरण चलाएँ

व्यवसाय प्रोफ़ाइल एकत्रीकरण

सर्वोत्तम अभ्यास

त्रुटि प्रबंधन

अगले चरण

webhook

स्टेटस

रिस्पॉन्स स्कीमा

​आर्किटेक्चर

​प्रमाणीकरण

​सत्र निर्माण

​होस्टेड लिंक भेजना

​पोलिंग बनाम webhooks

​Webhook हैंडलिंग

​निर्णयों को संभालना

​पुनः सबमिशन फ़्लो

​अपने फ़्रंट एंड से चरण चलाएँ

​व्यवसाय प्रोफ़ाइल एकत्रीकरण

​सर्वोत्तम अभ्यास

​त्रुटि प्रबंधन

​अगले चरण

webhook

स्टेटस

रिस्पॉन्स स्कीमा

आर्किटेक्चर

प्रमाणीकरण

सत्र निर्माण

होस्टेड लिंक भेजना

पोलिंग बनाम webhooks

Webhook हैंडलिंग

निर्णयों को संभालना

पुनः सबमिशन फ़्लो

अपने फ़्रंट एंड से चरण चलाएँ

व्यवसाय प्रोफ़ाइल एकत्रीकरण

सर्वोत्तम अभ्यास

त्रुटि प्रबंधन

अगले चरण