Skip to content

Part 10 — System Blueprint

Integration Catalog

The integration catalog is a build contract for external data, document, registry, mandate and payment rails. Every call must create an external_verification row or a domain-specific rail record, must reference an active consent_artifact where consent is required, and must publish only state-machine events that are legal for the current state.

RBI’s Digital Lending Directions require explicit, need-based consent with an audit trail, prohibit unauthorised LSP pool accounts, require borrower data storage in India, and require all DLA/LSP data collection to be purpose-bound (RBI Digital Lending Directions, 2025). Build the integration gateway as a regulated evidence system, not as a transient API client.

FieldTypeRequiredRule
integration_call_iduuidYesPrimary key for the gateway call.
providerenumYesUse existing external_verification.provider: pan_nsdl, gstn_vendor, udyam, ckyc, digilocker, aa, bureau, mca, cersai, bank_penny_drop, sanctions_vendor, internal. For ITR API/vendor use, add a controlled provider itr_eri_vendor before enablement; do not overload internal.
application_iduuidConditionalRequired for origination pulls.
party_iduuidConditionalRequired for party, KYC, bureau, PAN, Udyam, CKYC and sanctions checks.
loan_account_iduuidConditionalRequired for post-booking CERSAI, NeSL, payment, eNACH, CIC and monitoring calls.
consent_iduuidConditionalRequired for bureau_pull, gst_fetch, account_aggregator, digilocker, ckyc_fetch, udyam_verify, itr_fetch, bank statement upload and partner data sharing.
idempotency_keytextYesDeterministic key: subject id plus provider plus request type plus version.
request_payload_hashchar(64)YesStore hash, not sensitive payload, unless raw payload retention is legally and contractually permitted.
response_payload_uritextConditionalEncrypted raw response path where retention is allowed.
normalized_statusenumYesSame vocabulary as external_verification.normalized_status: success, no_hit, mismatch, temporary_failure, provider_error, consent_required, rejected.
normalized_jsonjsonbConditionalParsed fields used by rules, underwriting or operations.
retry_countintYesStarts at 0; max per integration below.
next_retry_attimestamptzConditionalRequired for temporary_failure.
terminal_eventenumConditionalState-machine event to publish only after successful validation.
Error classExamplesRetry ruleWorkflow effect
transport_timeoutNetwork timeout, DNS failure, TLS resetRetry 3 times with exponential backoff: 5 minutes, 30 minutes, 2 hours.Keep task waiting_external; do not advance state.
provider_5xxProvider unavailable, gateway internal errorRetry 3 times with 15 minutes, 1 hour, 4 hours unless provider publishes a longer window.If required data still missing, emit provider_retry_exhausted and route data_pending to on_hold.
rate_limitedHTTP 429 or provider quota exceededRetry after provider Retry-After; otherwise 1 hour, 4 hours, next business day.Alert integration owner; do not spam borrower for new consent.
validation_errorPAN format invalid, GSTIN checksum invalid, missing mandatory fieldNo retry.Return to returned_for_rework through data_or_identifier_deficient or deficiency_raised.
consent_expiredAA consent expired, DigiLocker token revoked, bureau consent invalidNo technical retry.Create new consent_artifact; keep data_pending or kyc_pending open.
provider_business_rejectNo CKYC record, bureau no-hit, Udyam not found, mandate rejectedNo retry unless borrower corrects input.Store no_hit, mismatch or rejected; rules decide whether rework, deviation or rejection is legal.
duplicate_requestSame idempotency key submitted twiceReturn previous normalized result.Do not create duplicate document_instance, mandate, payment_instruction or external_verification.
API/railProvider codePurposeLifecycle stageKey request fieldsKey response fieldsState/event hooksFailure handling
PAN validationpan_nsdlValidate PAN format, name match and active status for borrower, proprietor, promoter, director, partner, guarantor and beneficial owner.kyc_pending, prescreen_pendingparty_id, primary_pan or natural_person.pan, display_name, date of birth/incorporation when available, consent_id if journey uses consented fetch.PAN status, name match score, masked name, category, last updated date, mismatch reason.Success supports kyc_verified; mismatch creates returned_for_rework; fraud mismatch can trigger fraud_confirmed.Format/checksum failure no retry; provider 5xx retry; mismatch requires corrected PAN or KYC rejection.
Consumer credit bureaubureauPull individual bureau report for proprietors, promoters, co-applicants and guarantors.prescreen_pending, data_pending, monitoringparty_id, application_id, PAN, name, DOB, gender, mobile, address, enquiry purpose, consent_id with consent_type=bureau_pull.Score, enquiry id, tradelines, DPD history, suit-filed/wilful default flags where reported, write-off/settlement flags, active obligations, score reason codes.pre_screen_passed, hard_reject_triggered, data_pack_finalized, deviation_raised.No-hit is valid response; do not retry. Identity mismatch returns to KYC. Provider failure retries; exhausted required bureau pull routes to on_hold.
Commercial credit bureau and CMRbureauPull entity report, Commercial Credit Information Report and rank/band for business_entity.data_pending, credit_in_review, renewalEntity PAN, GSTIN, legal name, address, constitution, CIN/LLPIN where available, enquiry purpose, consent_id.Commercial score/rank, active credit facilities, sanctioned limits, overdue/NPA flags, related-party links, suit-filed/wilful default, bureau reference number.data_pack_finalized; adverse finding can create deviation or credit_rejected.No-hit allowed for new micro entity; mismatch requires corrected identifiers; provider failure retries.
Account Aggregator consent creationaaCreate AA consent artefact for bank account data or periodic monitoring.data_pending, monitoring, renewalparty_id, application_id, FIU id, AA handle, purpose code, data range, fetch type, frequency, consent validity, data life, account type.Consent handle/id, status, linked account references, expiry, rejection reason.Active consent permits AA data fetch; rejection keeps data_pending.Consent rejection no retry; borrower may initiate new consent. AA technical failure retries. ReBIT defines AA, FIP and FIU callback API groups for consent and data flow (ReBIT AA API specifications).
Account Aggregator data fetchaaFetch bank transactions, balances and account profile from FIPs through AA.data_pending, monitoringConsent handle, session id, FI data range, account link reference, request timestamp, encryption key material as per AA spec.Account profile, balances, transactions, masked account, fetch status, data range served, FIP id.Parsed BSA variables support data_pack_finalized; missing required account may create returned_for_rework.Retry data fetch on pending/temporary failure until consent expires; do not fetch beyond consent scope.
Bank statement analyzerinternal or vendor-specific extensionParse uploaded PDF/CSV/netbanking/AA statements into underwriting variables.data_pending, credit_in_reviewdocument_id or AA payload URI, account number masked, statement period, bank name, password metadata where borrower provided.ABB, monthly credits/debits, bounce count, EMI detection, counterparty concentration, circular transaction flags, fraud/tamper flags.Success supports data_pack_finalized; tamper flag can trigger fraud_confirmed or deviation_raised.Parser failure returns to document rework; tamper suspicion routes RCU, not silent waiver.
GST return and GSTIN analyticsgstn_vendorVerify GSTIN status and derive turnover, filing regularity, customer/supplier and e-way/e-invoice signals.data_pending, monitoring, working-capital renewalprimary_gstin, party_id, application_id, consent/OTP artefact, date range, return types requested: GSTR-1, GSTR-3B, e-invoice, e-way bill where available.GSTIN status, legal/trade name, registration date, cancellation status, filing periods, taxable value, tax paid, top counterparties, nil months, variance flags.data_pack_finalized, deviation_raised, hard_reject_triggered for cancelled GSTIN policy.OTP/consent expiry requires borrower action; provider 5xx retries; GSTIN cancelled is business result. GST API availability usually runs through GSP/ASP/vendor or consented rails, not arbitrary public lender access (GSTN e-invoice APIs).
ITR/financial tax dataitr_eri_vendor or internal for uploaded ITRValidate ITR acknowledgements, income, turnover, tax paid and financial statement consistency.data_pending, credit_in_reviewPAN, assessment years, acknowledgement numbers, borrower-authorised ERI/vendor consent, uploaded ITR document_id, audited financials document_id.ITR filing status, gross receipts, total income, tax paid/refund, balance sheet extracts where available, acknowledgement hash, mismatch flags.data_pack_finalized; mismatch with GST/banking can create deviation_raised.No generic unauthorised ITR pull is allowed. Income Tax ERI specs require taxpayer-authorised client/prefill flows (Income Tax API specifications); consent expiry requires re-consent; parse failure returns to documents.
Udyam verificationudyamVerify MSME registration, classification and enterprise details.kyc_pending, data_pending, PSL taggingUdyam Registration Number, PAN/GSTIN where available, enterprise name, consent_id with consent_type=udyam_verify.Udyam number, enterprise name, type, classification micro/small/medium, NIC codes, registration date, address, QR/verification evidence.Updates business_entity.udyam_registration_number and msme_classification; success supports data_pack_finalized.Not-found returns to rework or unverified; no official arbitrary lender API was verified in the domain docs, so store portal/vendor evidence.
CKYC search/download/uploadckycReuse or submit KYC records for individuals and legal entities.kyc_pending, periodic KYCPAN, CKYC id, name, DOB/incorporation, mobile, address, consent_id with consent_type=ckyc_fetch, KYC template fields.CKYC id, KYC type, masked identifiers, address, OVD details, image/document references where permitted, match confidence.Success updates kyc_profile.ckyc_id; supports kyc_verified only after BO and screening checks are complete.No-hit means fresh CDD; mismatch routes KYC rework; provider failure retries. RBI operationalised CKYCR through CERSAI from July 15, 2016 (RBI CKYCR circular).
DigiLocker document pulldigilockerFetch authentic issued documents with user consent.kyc_pending, docs_pending, documentation_pendingOAuth/OpenID request, scopes, document type, issuer id, borrower identifier, consent_id, redirect/callback id.Document URI, issuer, document type, issue date, XML/PDF metadata, hash, signer/certificate metadata.Creates document_instance; verified documents can move docs_pending to data_pending.Consent denial no retry; token expiry re-authenticates; document not available returns to manual upload. DigiLocker Requesters use OAuth 2.0/OpenID and user consent (DigiLocker Requester integration).
MCA/company mastermcaVerify companies/LLPs, directors, charges and company status.kyc_pending, credit_in_review, secured lendingCIN, LLPIN, company/LLP name, director DIN/PAN where available, party_id.Legal name, incorporation date, registered address, authorised/paid-up capital, status, directors/designated partners, charge index.Updates business_entity.cin, business_entity.llpin, entity_status; adverse status creates deviation or rejection.No retry for struck-off/dissolved status; provider technical failure retries; mismatch routes rework.
Sanctions, PEP, adverse media and negative listssanctions_vendorScreen parties, beneficial owners, guarantors, partners, DSAs and vendors.prescreen_pending, kyc_pending, partner onboarding, periodic monitoringparty_id, name, aliases, DOB/incorporation, PAN, nationality, address, role, list types.Match score, list source, category, watchlist id, summary, hit confidence, update timestamp.Creates screening_hit; true positive blocks kyc_verified and loan_booked.Provider failure retries; possible hit opens manual review; true positive exits only through kyc_rejected, on_hold or compliance clearance.
Bank account verification/penny dropbank_penny_dropVerify borrower, supplier, dealer, escrow and repayment bank accounts.documentation_pending, disbursement_pending, servicing bank changeAccount number, IFSC, account holder name, party id, beneficiary type, consent/authorisation evidence.Account status, name returned, match score, bank reference id, penny transaction id, failure code.Supports documents_executed_and_cps_cleared and payment_initiated; mismatch blocks disbursement.Name mismatch requires ops checker decision; invalid account no retry; bank rail timeout retries.
eSigndigilocker or eSign service provider extensionObtain legally valid electronic signatures on loan agreement, guarantee, board resolution and mandate where permitted.documentation_pending, mandate_setupDocument hash, signer party_id, signatory role, Aadhaar/eKYC or provider auth flow, callback URL, document version, consent/acceptance evidence.Signature event id, certificate serial, signer name, timestamp, hash signed, failure reason.Creates signature_event; all required signers enable documents_executed_and_cps_cleared.Signer rejection no retry; failed OTP/auth may retry 3 times; document hash mismatch invalidates pack. CCA describes eSign as signing document hash with e-KYC authentication (CCA eSign).
eStampinternal or stamp vendor extensionProcure or verify state stamp duty certificates for loan/security documents.documentation_pendingState, article/instrument, consideration/loan amount, first party, second party, stamp amount, document id.Certificate number, state, amount, issue date, GRN/reference, payer, verification status.Creates stamp_certificate; stamp success supports documents_executed_and_cps_cleared.Wrong state/article/amount requires cancellation or additional stamp per legal policy; provider failure retries; no silent downgrade to unstamped document.
eNACH/NACH mandate registrationRail-specific mandate provider; writes mandateRegister recurring repayment debit mandate.documentation_pending, disbursement_pending, servicing bank changeloan_account_id, party_id, bank_account_id, max amount, frequency, start/end date, mandate type enach, sponsor bank, utility code.UMRN, mandate status, rejection reason, sponsor/destination bank timestamps, accepted amount and frequency.mandate_activated supports documents_executed_and_cps_cleared or disbursement guard.Rejected status requires borrower reattempt or alternate mandate; bank timeout retries status enquiry. NPCI says debit can start only after mandate acceptance and UMRN is 20 digits with fifth digit “6” for eSign mandates (NPCI eMandate FAQ).
CERSAI search/filing/satisfactioncersaiSearch existing security interests, register charge, modify and satisfy charge.collateral-valuation-legal, documentation_pending, post-closureBorrower party, PAN/CIN, collateral details, security_charge_id, charge type, charge amount, creation date, asset id, lender details.Search result, filing id, registration number, status, fee, error list, satisfaction acknowledgement.Creates/updates security_charge.cersai_filing_id; cersai_filed supports secured disbursement; satisfaction supports closure.Search failure blocks secured disbursement; filing rejection returns to legal/ops; retry technical failures only. SARFAESI provides the central registry basis (India Code SARFAESI section 20).
NeSL Information UtilityExternal IU integration; normalized into document/evidence recordsSubmit debt records, get borrower authentication and store evidence of debt/default.documentation_pending, loan_booked, default/legal recoveryBorrower identifiers, loan terms, sanction id, document hash, repayment obligations, authentication request, default details when applicable.IU record id, authentication status, borrower response, evidence timestamp, default record status.Authenticated debt evidence supports legal readiness; default evidence supports legal_route_requested.Authentication pending remains waiting; borrower dispute routes legal review; technical failure retries. NeSL is registered as an Information Utility under IBBI (PIB NeSL registration).
Disbursement payment rails: NEFT/RTGS/IMPS/UPIPayment service provider or bank host-to-host; writes payment_instruction and loan_transactionSend loan proceeds to borrower, supplier, dealer, invoice seller, escrow or statutory authority.disbursement_pending, loan_bookedBeneficiary account/IFSC or UPI id, beneficiary type, amount, payment mode, sanction/disbursement id, purpose, maker/checker approval, escrow id where CLA applies.Bank UTR/reference, status initiated/posted/failed/reversed, failure code, value date.Success supports loan_booked; failure emits disbursement_failed and may trigger booking_failed.Pending status enquiry every 15 minutes for 2 hours, then hourly until end of day; failed payment requires checker-approved reinitiation; no LSP/pool account except permitted co-lending escrow under RBI Digital Lending Directions.
Repayment/payment collection rails: NACH debit, UPI collect, payment gateway, bank virtual accountPayment rail provider; writes loan_transactionCollect dues directly into RE account or permitted CLA escrow.Servicing, collectionsloan_account_id, due id, amount, mandate/UPI/payment link id, payer party, expiry, payment purpose.Receipt reference, amount, payer account masked, settlement status, bounce/failure code, value date.receipt_posted, bounce, dpd_changed, arrears_cleared.Bounce is business event; not retried unless mandate policy allows representation. Pending settlement reconciled daily; unapplied receipts open suspense item.
CIC reporting file exchangeCIC member integration; writes cic_submissionReport consumer/commercial/MFI credit information and corrections.loan_booked, servicing, delinquency, closureBorrower identifiers, co-borrower/guarantor links, account number, sanctioned amount, current balance, DPD, asset classification, suit-filed/wilful default, closure status, CERSAI property registration where applicable.File ack, accepted/rejected counts, reject reasons, DQI score where provided, dispute/correction ack.Supports compliance reporting; reject correction creates compliance task.Rejected records fixed before next reporting date. As of July 2026, support configurable reporting calendar: at minimum fortnightly 15th/last-day cycles under RBI CIC Directions, and entity-specific amended CI schedules where applicable (RBI CIC Directions, 2025 public mirror).

Data Retention And Security By Integration

Section titled “Data Retention And Security By Integration”
Integration categoryStore raw response?Store normalized data?Special control
Bureau/CICStore encrypted report only for approved credit purpose and regulatory retention; mask in UI.Yes: score, obligations, DPD, adverse flags and enquiry id.Access limited to credit_analyst, credit approver, RCU, compliance and audit.
AA/bank dataStore encrypted raw payload for underwriting evidence within consent/data-life and regulatory retention policy.Yes: transaction variables and account profile.Do not fetch outside consent scope; periodic monitoring consent must be separate.
GST/ITRStore encrypted evidence and parsed variables used in CAM.Yes: turnover, filing, tax and mismatch variables.Treat tax data as high sensitivity; partner APIs cannot receive raw tax payload unless explicit consent and contract permit it.
KYC/DigiLocker/CKYCStore document hash, document URI and verified KYC fields.Yes: status, identifiers, BO status and verification result.Full Aadhaar storage is prohibited unless legally permitted; store aadhaar_last4 only.
eSign/eStamp/eNACHStore certificate/signature/UMRN and immutable evidence.Yes: status and references.Document hash mismatch invalidates execution evidence.
CERSAI/NeSLStore registry acknowledgements and IU evidence.Yes: filing/authentication status and references.Required for secured disbursement, enforcement and closure release.
Payment railsStore bank reference, status, value date and reconciliation records.Yes: loan_transaction and escrow_movement.Daily reconciliation to bank/escrow/GL is mandatory.