लेन-देन निगरानी इंटीग्रेशन: KYT API

यह गाइड लेन-देन निगरानी के पूरे इंटीग्रेशन ढाँचे को कवर करती है। त्वरित शुरुआत आपको चालू कर देता है; यह पेज आपको प्रोडक्शन तक ले जाता है।

आर्किटेक्चर

प्रमाणीकरण

मानक x-api-key हेडर। वही कुंजियाँ सत्र और इकाइयों के लिए भी उपयोग होती हैं। API प्रमाणीकरण देखें।

लेन-देन सबमिट करना

एक ही endpoint: POST /v3/transactions/। पूरी स्कीमा के लिए लेन-देन सबमिट करना देखें। न्यूनतम payload:

{
  "transaction_id": "tx-0001",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "500.00",
    "currency": "EUR"
  },
  "subject": { "entity_type": "person", "vendor_data": "user-42", "full_name": "John Doe" },
  "counterparty": { "entity_type": "company", "full_name": "Acme Corp" }
}

पेमेंट मेथड, डिवाइस संदर्भ और कस्टम प्रॉपर्टी वाला विस्तृत payload:

{
  "transaction_id": "tx-0002",
  "transaction_at": "2026-04-16T10:00:00Z",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "12500.00",
    "currency": "USD",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "person",
    "vendor_data": "user-42",
    "full_name": "John Doe",
    "country_code": "US",
    "device_context": {
      "fingerprint": "fp-9f2c...",
      "user_agent": "Mozilla/5.0 ...",
      "browser_family": "Chrome",
      "platform": "web",
      "network_context": { "ip_address": "203.0.113.5" }
    },
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US12345678901234567890",
      "issuing_country": "US"
    }
  },
  "counterparty": {
    "entity_type": "company",
    "vendor_data": "biz-acme",
    "full_name": "Acme Corp",
    "country_code": "US",
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US09876543210987654321",
      "issuing_country": "US"
    }
  },
  "custom_properties": {
    "invoice_id": "INV-2026-00042",
    "category": "b2b_goods"
  }
}

हर टॉप-लेवल फ़ील्ड के लिए camelCase एलियास स्वीकार किए जाते हैं (txnId, txnDate, type, info, applicant, props, travelRule, includeCryptoScreening)। SDK का वायर फ़ॉर्मैट और snake_case फ़ॉर्मैट एक ही जगह पहुँचते हैं।

पक्ष मॉडलिंग

हर लेन-देन में एक अनिवार्य subject होता है (आपका ग्राहक, यानी वह पक्ष जिसकी आप निगरानी करते हैं) और एक वैकल्पिक counterparty (दूसरा पक्ष) होता है। हर पक्ष का अपना payment_method और वैकल्पिक device संदर्भ होता है। रिस्पॉन्स में ये parties ऐरे में भूमिकाओं APPLICANT और COUNTERPARTY के साथ आते हैं। जिस पक्ष में vendor_data नहीं होता, उसे बाहरी स्नैपशॉट (kind: EXTERNAL) के रूप में संग्रहीत किया जाता है, और उससे कोई इकाई लिंक नहीं होती। पक्ष के फ़ील्ड के लिए लेन-देन payload देखें।

आइडेम्पोटेंसी

txn_id (वह transaction_id जो आप भेजते हैं) हर एप्लिकेशन में अनूठा होता है। जो transaction_id पहले से मौजूद है, उसे दोबारा सबमिट करने पर transaction_id फ़ील्ड पर A transaction with this transaction_id already exists. संदेश के साथ 400 मिलता है; जब दो एक जैसे अनुरोध एक साथ आ जाएँ, तो दूसरे को 409 मिलता है। इनमें से कोई भी रिस्पॉन्स मौजूदा लेन-देन नहीं लौटाता। डुप्लिकेट transaction_id पर 400 या 409 मिलने पर दोबारा सबमिट करने के बजाय मौजूदा लेन-देन खोजें: पहले रिस्पॉन्स के uuid का उपयोग करके GET /v3/transactions/{uuid}/ से उसे पढ़ें, या transaction.created webhook के साथ आपके txn_id के बगल में आने वाले transaction_id (Didit uuid) का उपयोग करें। txn_id हमेशा सबमिट करने से पहले अपनी तरफ़ से बनाएँ; आइडेम्पोटेंसी के लिए Didit द्वारा बनाए गए ID पर निर्भर न रहें। अपना डेटाबेस ID, UUID, या लेन-देन फ़ील्ड का हैश इस्तेमाल करें।

रियल-टाइम बनाम बैच

रियल-टाइम: ज़्यादातर उपयोग के मामलों के लिए अनुशंसित। लेन-देन होते ही अपने सिस्टम से सबमिट करें। नियम सिंक्रोनस रूप से मूल्यांकित होते हैं और निर्णय लौटाते हैं।
बैच / बैकफ़िल: ऐतिहासिक इंजेस्चन के लिए txn_date को अतीत की तारीख के साथ भेजें। नियम फिर भी चलते हैं और webhook ट्रिगर कर सकते हैं। बैकफ़िल पर नियम ट्रिगर होने से बचने के लिए, कंसोल के CSV इंपोर्ट में “dry ingest” फ़्लैग का उपयोग करें।

ऐतिहासिक इंजेस्चन

जब आप किसी दूसरे लेन-देन निगरानी सिस्टम से माइग्रेट कर रहे हों:

अपने ऐतिहासिक लेन-देन को CSV में एक्सपोर्ट करें।
कंसोल में Transactions → Import history का उपयोग करें (या लूप में API से सबमिट करें), और txn_date को अतीत की तारीख के साथ रखें।
इंजेस्चन पूरा होने के बाद ही नियम सक्षम करें, या नियम मूल्यांकन छोड़ने के लिए dry ingest का उपयोग करें।

ऐतिहासिक नियम मूल्यांकन के बारे में सोच-समझकर फ़ैसला लें। इतिहास के 6 महीनों को “30 दिनों में 20 ट्रांसफ़र” वाले नियम से गुज़ारने पर एक साथ हज़ारों अलर्ट बनेंगे।

webhook

इनकी सदस्यता लें:

transaction.created: सबमिट किया गया हर लेन-देन।
transaction.status.updated: स्थिति में बदलाव (जैसे कि कोई विश्लेषक IN_REVIEW से APPROVED पर ले जाए, या कोई एसिंक्रोनस AML जाँच स्कोर अपडेट करे)।

पूरी जानकारी: TM webhook।

app.post('/webhooks/didit-tm', (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();

  const { webhook_type, status, txn_id } = req.body;
  if (webhook_type === 'transaction.status.updated' && status === 'DECLINED') {
    suspendTransaction(txn_id);
  }
  res.status(200).end();
});

स्थिति संभालना

स्थिति	क्या करें
`APPROVED`	लेन-देन को सामान्य रूप से प्रोसेस करें।
`IN_REVIEW`	विश्लेषक की समीक्षा या स्वचालित पुनः जाँच से स्थिति का समाधान होने तक लेन-देन रोके रखें।
`DECLINED`	लेन-देन अस्वीकार करें। उपयोगकर्ता को एक सामान्य त्रुटि दिखाएँ।
`AWAITING_USER`	लेन-देन पूरा होने से पहले उपयोगकर्ता को कार्रवाई करनी होगी: `action_required` ब्लॉक पढ़ें और उसका `url` उपयोगकर्ता तक पहुँचाएँ (SDK इसे स्वचालित रूप से संभाल सकते हैं)।

TM स्थितियाँ देखें।

लेन-देन को इकाइयों से जोड़ना

हर पक्ष के साथ vendor_data भेजें। इसके लाभ:

हर लेन-देन उपयोगकर्ता या व्यवसाय प्रोफ़ाइल में एकत्र होता है।
वेग और व्यवहार संबंधी नियमों के पास मूल्यांकन के लिए पूरा इतिहास होता है।
किसी इकाई को ब्लॉक करना भविष्य के लेन-देन पर अपने आप लागू हो जाता है।

vendor_data न होना कोई हार्ड एरर नहीं है: लेन-देन बाहरी स्नैपशॉट के रूप में संग्रहीत हो जाता है, लेकिन इकाई-स्तर का एकत्रीकरण छूट जाता है।

रेमेडिएशन सत्र

जब कोई नियम क्रिया किसी लेन-देन को AWAITING_USER पर ले जाती है, तो Didit स्वतः एक रेमेडिएशन सत्र बनाता है। यह उसी vendor_data के लिए एक मानक होस्टेड सत्यापन सत्र होता है। कस्टम नियम हमेशा क्रिया पर ही वर्कफ़्लो का नाम देते हैं। लाइब्रेरी नियमों के लिए वर्कफ़्लो आपकी लेन-देन सेटिंग्स में रेमेडिएशन वर्कफ़्लो पर वापस आता है, फिर आपके एप्लिकेशन का बायोमेट्रिक प्रमाणीकरण वर्कफ़्लो (जब विषय के पास संग्रहीत संदर्भ चेहरा हो), और फिर आपके एप्लिकेशन का डिफ़ॉल्ट वर्कफ़्लो। Travel Rule के लेन-देन इस स्वचालित फ़ॉलबैक से बाहर रखे गए हैं, क्योंकि उनकी लंबित क्रिया वॉलेट स्वामित्व का प्रमाण है। लेन-देन (प्रतिक्रिया, हर बाद की रीड और हर webhook) इसे कैनोनिकल action_required ब्लॉक में शामिल करता है:

{
  "status": "AWAITING_USER",
  "action_required": {
    "type": "verification_session",
    "url": "https://verify.didit.me/session/...",
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "status": "Not Started"
  },
  "remediation": {
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "url": "https://verify.didit.me/session/...",
    "status": "Not Started"
  }
}

remediation पश्चगामी संगतता के लिए रखा गया है। action_required मानक ब्लॉक है, और इसमें Travel Rule ट्रांसफ़र के लिए wallet_ownership क्रियाएँ भी शामिल होती हैं। wallet_ownership क्रिया अपने आप लेन-देन की स्थिति नहीं बदलती: लेन-देन वही स्थिति रखता है जो आपके नियम उसे देते हैं, जो अक्सर APPROVED होती है। इसलिए हर प्रतिक्रिया में action_required की जाँच करें, केवल AWAITING_USER पर नहीं। उपयोगकर्ता सत्यापन पूरा करता है। बायोमेट्रिक प्रमाणीकरण वर्कफ़्लो के लिए इसका मतलब है कि लाइवनेस जाँच वाली सेल्फ़ी को उसके मूल KYC ऑनबोर्डिंग के समय कैप्चर किए गए चेहरे से मिलाया जाता है। यह उच्च-मूल्य वाले लेन-देन के लिए सबसे मज़बूत अतिरिक्त चरण है। जैसे ही सत्र किसी निर्णय तक पहुँचता है, लेन-देन उसका अनुसरण स्वतः करता है: APPROVED (decision_reason_code: user_action_approved), DECLINED (user_action_declined), या IN_REVIEW (user_action_in_review), और transaction.status.updated webhook ट्रिगर होता है।

KYB को छोड़कर किसी भी प्रकार का वर्कफ़्लो चुना जा सकता है। बायोमेट्रिक प्रमाणीकरण वर्कफ़्लो (और वे वर्कफ़्लो जिनमें चेहरा मिलान, पहचान सत्यापन से पहले चलता है) के लिए ज़रूरी है कि विषय के पास किसी स्वीकृत सत्यापन से संग्रहीत संदर्भ चेहरा पहले से हो। जिन उपयोगकर्ताओं के पास यह नहीं है, उन्हें इसके बजाय आपके एप्लिकेशन के डिफ़ॉल्ट वर्कफ़्लो पर भेजा जाता है, और लेन-देन पर इस बदलाव का नोट दर्ज होता है।

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

अभ्यास	कारण
हमेशा `vendor_data` पास करें	एकत्रीकरण संभव होता है।
अपना `txn_id` इस्तेमाल करें	आइडेम्पोटेंसी।
`transaction.created` और `transaction.status.updated` दोनों की सदस्यता लें	असिंक्रोनस स्थिति बदलावों को पकड़ें (जैसे विश्लेषक समीक्षा के परिणाम)।
नियम थ्रेशोल्ड जानबूझकर सेट करें	कम थ्रेशोल्ड = अधिक अलर्ट; ज़्यादा = छूटे हुए जोखिम अधिक। जोखिम स्कोरिंग देखें।
कंसोल में नियम के चलने की गिनती की निगरानी करें	ऐसे नियम पकड़ें जो कभी ट्रिगर नहीं होते (गलत कॉन्फ़िगर) या हर चीज़ पर ट्रिगर होते हैं (बहुत ढीले)।
लाइव जाने से पहले TEST मोड में नियमों का परीक्षण करें	नियम देखें।

रेट लिमिट

रेट लिमिटिंग देखें। लेन-देन बनाना सबसे अधिक थ्रूपुट वाले endpoint में से एक है; आम सीमाएँ सैकड़ों अनुरोध प्रति सेकंड के आसपास होती हैं। सावधानी से बर्स्ट करें।

अगले चरण