KYC integration is how a bank, NBFC, fintech, insurer, gaming operator, or crypto exchange embeds third-party identity verification into an existing product or workflow. Most teams reach for the term “API integration” first, but the operational reality is broader. There are three distinct integration patterns (API-first, SDK-embedded, and hosted-flow), each with specific trade-offs. The integration choice usually decides drop-off, latency, and audit-trail continuity more than the vendor choice itself does.
Integration is where most KYC programmes either work or quietly stop working. The architecture, the code samples, the stack-specific patterns, the buy-versus-build calculus, the testing checklist that decides whether the integration survives production, and the anti-patterns that compound silently when no one catches them early all sit on the engineering side of the line. The overview of what KYC compliance involves covers the regulatory framing that the engineering decisions have to honour.
What KYC integration actually means in 2026
KYC integration is the embedding of identity verification, AML screening, and ongoing-monitoring capabilities into an existing customer-onboarding stack. It is the engineering work that takes a vendor product and makes it operational inside the institution’s own systems. That work is small if the stack is modern and the vendor is opinionated. It is substantial if the stack is legacy and the institution wants tight control of the UX.
Definition and the three integration patterns
Three patterns dominate. API-first: the institution’s backend calls the vendor over HTTPS for each verification step, owns the customer-facing UX entirely, and orchestrates the workflow. SDK-embedded: the vendor ships a mobile or web SDK that the institution embeds into its own application, with the SDK rendering the verification UI. Hosted-flow / iframe: the vendor renders the entire verification experience and the institution embeds an iframe or redirects the customer to a vendor-hosted URL.
Why integration choice matters more than vendor choice
Two vendors with similar capabilities can produce very different production outcomes if the integration models differ. Latency budgets vary: API-first integrations can be tightly tuned but require more engineering investment, SDK-embedded options reduce engineering effort but expose the institution to SDK-version churn, and hosted flows ship fastest but cede UX control. Drop-off varies too: a poorly-designed hosted flow can underperform a well-designed API-first integration on the same vendor product. So can audit-trail continuity. Hosted flows often produce vendor-side logs that the institution must pull; API-first integrations naturally generate institution-side logs from the start.
The three integration patterns: when to use which
The decision is rarely about engineering preference alone. It is about engineering bandwidth, UX requirements, time-to-market, and the existing technology stack. The right pattern usually picks itself once those four are honest.
API-first integration
Best for backend-heavy stacks where the institution wants full control of the customer-facing UX, multi-product orchestration where verification is one step inside a longer flow, and server-to-server flows where mobile or web rendering is not the bottleneck. The trade-off: the institution owns the UX and therefore owns the failure modes. Every error message, every retry, every edge case ships with the institution’s brand. Engineering investment is highest, but flexibility is also highest.
SDK-embedded integration
Best for mobile-first applications where the SDK can deliver native performance, fast time-to-market where the institution wants the vendor to handle the verification UI, and use cases where consistency across mobile and web is a priority. The trade-off: SDK-version dependency means the institution must keep up with vendor releases, and customising the UI beyond the SDK’s options is harder than customising an API-driven flow.
Hosted-flow / iframe integration
Best for web-first onboarding where the institution wants minimal engineering effort, low-volume launches where the cost of building a custom flow exceeds the cost of accepting a vendor-rendered one, and use cases where the institution explicitly wants the vendor’s flow as part of the trust signal. The trade-off: the least UX control of the three patterns, but the fastest path to launch.
Decision matrix: pattern, stack, and team size
| Stack profile | Engineering bandwidth | Recommended pattern |
|---|---|---|
| Backend-heavy fintech (Node.js / Go / Java) | Available | API-first |
| Mobile-first consumer app (iOS + Android) | Available | SDK-embedded |
| Bank with core-banking integration | Variable | API-first with vendor-side orchestration |
| Early-stage product, time-to-market priority | Limited | Hosted-flow |
| Multi-product platform | Available | API-first |
Reference architecture: REST and webhook flow
This is the architectural anchor most engineering teams need but rarely find written down clearly. Two flows cover most of what KYC integration actually has to do: synchronous and asynchronous.
Synchronous verification flow
A single REST request, an immediate response. The institution sends customer data and document images to the vendor, the vendor performs OCR, validation, and biometric checks in-call, and the response carries the verification decision. This works for instant decisions where the vendor’s processing fits inside a sub-second SLA: Aadhaar OTP eKYC against UIDAI, simple document OCR, and basic sanctions screening on a small list.
Asynchronous verification flow
A POST request initiates the verification, and a webhook callback delivers the outcome. The institution sends customer data, the vendor returns a session ID immediately, and the vendor performs the verification (which may include V-CIP, manual review, or slow document processing). The vendor then POSTs to the institution’s webhook endpoint with the final decision. This is the dominant pattern for V-CIP, video KYC, and any flow where the verification cannot complete inside a single HTTP timeout.
Sandbox vs production environments
Every serious vendor provides a sandbox with test identities: pass identities, fail identities, and edge-case identities (PEP-flagged, sanctions-listed, document-mismatched) that exercise the full decision tree. Production cutover requires explicit URL changes, credential rotation, and a small set of real-customer pilots before full traffic ramp. Hard-coding sandbox URLs in production is one of the most common anti-patterns. The fix is environment-driven configuration: URLs and credentials read from environment variables at runtime, never compiled into the binary or committed to source control.
Code-level integration sample
The code samples below use a generic https://api.example.com/... placeholder. Replace with the vendor’s actual endpoint paths from their developer documentation, and always verify the path against the vendor’s published API reference.
cURL request example
A POST to initiate identity verification:
“bash curl -X POST "https://api.example.com/v1/verifications" \ -H "Authorization: Bearer ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "customer_id": "cust_8f2b1c", "document_type": "aadhaar", "document_image_url": "https://uploads.example.com/img/abc123", "callback_url": "https://your-app.example.com/webhooks/kyc" }' “
The response carries a session identifier:
“json { "session_id": "sess_z1q9y4", "status": "pending", "created_at": "2026-04-27T10:15:23Z" } “
Node.js client example
A compact, copy-pasteable client wrapper:
“`javascript const fetch = require(‘node-fetch’);
async function initiateVerification(customer) { const res = await fetch(‘https://api.example.com/v1/verifications’, { method: ‘POST’, headers: { ‘Authorization’: Bearer ${process.env.KYC_API_KEY}, ‘Content-Type’: ‘application/json’, }, body: JSON.stringify({ customer_id: customer.id, document_type: customer.docType, document_image_url: customer.docUrl, callback_url: process.env.KYC_WEBHOOK_URL, }), }); if (!res.ok) throw new Error(KYC initiation failed: ${res.status}); return res.json(); } “`
Webhook handler skeleton
The handler must verify the signature before trusting the payload:
“`javascript const crypto = require(‘crypto’);
function verifySignature(rawBody, signatureHeader, secret) { const expected = crypto .createHmac(‘sha256’, secret) .update(rawBody) .digest(‘hex’); return crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(signatureHeader) ); }
app.post(‘/webhooks/kyc’, (req, res) => { const valid = verifySignature( req.rawBody, req.headers[‘x-signature’], process.env.KYC_WEBHOOK_SECRET ); if (!valid) return res.status(401).end(); // dispatch payload to the verification handler return res.status(200).end(); }); “`
The signature check is non-negotiable. A webhook endpoint without signature verification is a replay-attack vector, and that vector tends to surface in the first audit after launch.
Stack-specific integration patterns
Generic integration content does not survive contact with real production stacks. The patterns below are the ones that come up most often when engineering teams are scoping a KYC integration into a CRM or core banking platform.
Salesforce Financial Services Cloud
KYC plugs into the Lead, Opportunity, and Account journey. The standard pattern is a custom Apex callout from the Lead-conversion trigger to the KYC vendor, with the verification result written back to the Account object’s KYC custom fields. Object-mapping best practices: keep KYC status as an enumerated picklist (Validated, Registered, On Hold, Rejected) rather than free text, and store the verification timestamp and the underlying provider session ID for audit.
Microsoft Dynamics 365
There are two architectural choices here. The out-of-box approach extends the Contact and Account entities with KYC custom fields, and triggers verification from a Power Automate flow. The custom-entity approach creates a dedicated KYC Verification entity that holds the full verification record, with one-to-many relationships to Contact and Account. The custom-entity approach scales better for multi-product institutions where a single customer may have multiple verification events.
Core banking: Temenos T24
T24 integration runs through the standard T24 web services or the newer Transact APIs. KYC verification typically fires at customer onboarding (CUSTOMER application creation) and at periodic update (CUSTOMER amendment). Real-time sync works for new account opening, while batch sync is acceptable for periodic updation where the volume is high but latency tolerance is generous. The institution’s middleware (often an ESB or an iPaaS) typically sits between T24 and the KYC vendor to handle data-format translation and audit logging.
Core banking: Finacle
Finacle integration runs through the Finacle Integrator or the modern API gateway. The standard pattern fires KYC verification on the GENERAL_LEDGER_CIF_OPEN flow and on subsequent customer-record amendments. Customer-record sync requires careful handling of the KYC Identifier: when the vendor returns a verified record, the Finacle CIF must be updated with the verification status and the underlying KYC Identifier so it can be re-used across products.
Modern core banking: Mambu
Mambu’s API-first architecture makes KYC integration substantially simpler than legacy core banking. The standard pattern is a webhook-driven flow: Mambu fires a webhook on Client creation, the institution’s backend receives the webhook, calls the KYC vendor, and updates the Mambu Client record with the verification result. The whole loop typically runs sub-second for digital channels and sub-minute for V-CIP.
SDK vs API vs hosted-flow: decision framework
This is the condensed decision framing. If you only have time to absorb one section before scoping, this is the one.
When SDK wins
Mobile-first onboarding where the SDK delivers near-native performance. Engineering bandwidth is limited and the vendor’s UI is acceptable. Time-to-market is the priority and the SDK’s UX customisation is sufficient for the institution’s brand. The Aadhaar eKYC channel is well-served by SDK integration in mobile-first contexts.
When API wins
Custom UX requirements that exceed what the SDK can deliver. Multi-product orchestration where verification is one step inside a longer institutional flow. Multi-vendor failover where the integration must abstract across vendors. Server-to-server flows where the customer experience does not depend on vendor-side rendering at all.
When hosted flow wins
Speed-to-launch as the dominant priority. Engineering bandwidth genuinely limited. Web-first onboarding where the customer is willing to redirect to a vendor-rendered page. Use cases where the vendor’s UX is part of the trust signal: the customer recognises the verification provider and trusts the brand association.
Buy vs build: the honest cost comparison
Most engineering teams reach for this framework too late, after the build has accumulated more sunk cost than the buy alternative ever would have. The honest comparison is short.
True cost of building KYC in-house
There are several hidden cost lines. OCR engineering means building or licensing OCR that handles 190+ countries’ identity documents at production accuracy. Biometric and liveness work is research-grade, with iBeta-level certification expectations. Sanctions, PEP, and adverse media data feeds carry recurring license costs from Refinitiv, ComplyAdvantage, or LexisNexis, plus the engineering to ingest and update them. Continuous monitoring engineering covers re-screening pipelines, change-of-circumstance triggers, and alert routing. And a compliance team has to keep up with regulator changes from FATF, RBI, FinCEN, EU AMLR, MeitY, and more. The end-to-end build typically takes a multi-year programme and ongoing investment that scales with regulatory cadence.
True cost of buying
Per-verification spend that scales with onboarding volume. Integration engineering as a one-time cost (typically two to six engineering-weeks for an API-first integration, one to two weeks for hosted) plus maintenance overhead from vendor SDK updates, occasional API breaking changes, and monitoring drift. Vendor governance covers annual review, certification verification, and contract renegotiation. Total cost of ownership for buying is heavily dominated by per-verification spend at scale, with integration costs amortising fast.
Hybrid: orchestrating multiple vendors
Some institutions run multi-vendor strategies: a primary vendor for dominant geographies, fallback vendors for edge cases, and category-specific specialists for capabilities the primary lacks. The cost of orchestration is an abstraction layer that normalises across vendor APIs, plus the operational cost of monitoring multiple vendor relationships. The cost of single-vendor lock-in is whatever you pay if you don’t have a fallback when the primary has an outage or a contract dispute. Most institutions reach the multi-vendor decision when the primary vendor’s coverage gaps become operationally material, not before.
Testing checklist before going live
Production readiness is not the same as integration completion. The checklist below is what separates a working integration from one that survives its first month of real traffic.
Sandbox test identities
Pass identities verify that the success path runs end-to-end. Fail identities verify the failure paths render correctly to the customer and propagate to compliance review. Edge-case identities (PEP-flagged, sanctions-listed, document-quality-degraded, previously-rejected) verify the full decision tree exercises every branch. Most vendors publish a test identity catalogue, and the institution should test every identity in it before launch.
Failure-mode simulation
Liveness rejection: what does the customer see, what does compliance see, what is logged. OCR failure: same questions. Sanctions hit: does the alert route to the right queue, with the right priority, with the right metadata. Network timeout: does the system retry sensibly, or does it leave the customer in an indeterminate state. Each failure mode needs an explicit test case, not a wave of the hand.
Performance and load testing
Latency budget per call: the institution’s SLA for the customer-visible part of the flow, with the verification call’s contribution carved out explicitly. Throughput at peak onboarding hours: typical fintech onboarding traffic concentrates in evenings, and load testing should match that profile. The video KYC API documentation and document verification OCR API cover specific endpoint-level expectations for the channels they support.
Post-integration operations
Lifecycle thinking matters as much as launch readiness. The integration that ships clean still has to keep working, and that means monitoring and switchover plans from day one.
Monitoring and SLAs
Latency dashboards per endpoint, with alerting on P95 breaches. Error-rate alerting tied to specific failure modes (vendor 5xx vs vendor 4xx vs network errors), because the response is different in each case. Vendor-status integration where the vendor publishes a status page or a status API. Most institutions discover they should have built monitoring on day one only after their first vendor outage, when the post-mortem makes the gap obvious.
Vendor switchover and multi-vendor failover
An abstraction layer in the institution’s code (a verification interface that normalises across vendor APIs) turns a disruptive switchover into a configuration change. The investment is real-time, but it pays back the first time the institution needs to switch vendors, evaluate a new entrant, or run multi-vendor failover. Real-world failover triggers include vendor outages exceeding the institution’s SLA, vendor contract disputes, and regulatory direction shifts that make the existing vendor non-compliant.
Common integration anti-patterns
These are the patterns that compound silently if no one catches them early. Each is preventable with a one-line check at the right point in the integration cycle.
Calling the API synchronously when it should be async
Symptom: HTTP timeouts when the verification cannot complete inside the connection lifetime. The customer drops off, the error rate climbs, and the team adds aggressive retries that compound the problem. Fix: use the asynchronous webhook flow for any verification involving V-CIP, manual review, or slow document processing.
Skipping webhook signature verification
Symptom: the institution accepts arbitrary payloads as legitimate verification results, which allows a replay attack to mark fraudulent customers as verified. Audit failure follows. Fix: every webhook handler must verify the HMAC signature against the shared secret before acting on the payload, with timing-safe comparison.
Hardcoding sandbox URLs in production
Symptom: production traffic silently routes to sandbox. Verification results look successful but no real customer is being verified. Fix: read endpoint URLs from environment configuration, never from code. Production launch checklists should explicitly verify environment variables, and CI should fail builds that reference sandbox hosts in production code paths.
Not handling re-screening events
Symptom: the institution onboards customers cleanly but never updates KYC after onboarding. Risk ratings go stale, sanctions hits on existing customers go unnoticed, and audit failure follows. Fix: implement the webhook flow for ongoing monitoring events from day one, even if the institution doesn’t yet have a downstream alert routing system.
Security and compliance for the integration itself
This is the layer most published guides skip, and the layer that decides whether the integration passes its first regulatory inspection.
PII in transit
TLS for every connection, mTLS where the institution’s risk profile warrants it. Signed payloads beyond TLS for end-to-end integrity guarantees. Encrypted storage at rest, with key rotation cadences appropriate to the regulatory regime. The sanctions screening reference covers the discipline that runs alongside identity verification.
Data residency
India’s DPDP Act for Indian customers, GDPR for EU customers, and regional cloud regions where the vendor offers them. Architectures that ignore residency either fail audit or get refactored expensively when the regulator surfaces the issue. The recent RBI Master Direction amendments reinforced data-handling expectations under the Indian framework.
Tokenisation and redaction
Mask Aadhaar numbers (first eight digits) on all stored copies. Tokenise PII in non-production environments; sandbox should never carry real customer data. Redact request and response logs before sending them to centralised logging systems. The customer due diligence reference covers the broader discipline, while AML compliance and KYC best practices cover the institutional context.
For institutions wanting to evaluate specific HV API endpoints, the fraud detection API and adjacent marketplace listings cover the integration depth available. The end-to-end KYC process reference covers the broader workflow.
See how HyperVerge integrates with your CRM, core banking, or modern stack
If you are scoping a KYC integration into Salesforce FSC, Dynamics 365, Temenos, Finacle, Mambu, or a custom modern stack, and want to see how the API patterns, webhook orchestration, and core-banking touchpoints work in practice, book a working session with our solutions team. The integrations marketplace pages cover specific endpoint-level documentation for individual capabilities.
FAQs
What is KYC integration?
KYC integration is the engineering work that embeds third-party identity verification, AML screening, and ongoing-monitoring capabilities into an existing customer-onboarding stack. The three dominant patterns are API-first, SDK-embedded, and hosted-flow, each with specific trade-offs around UX control, engineering effort, and time-to-market.
How do I integrate a KYC API?
Start with the vendor’s developer documentation and sandbox. Build a thin API client wrapper in your backend language. Implement a webhook handler with signature verification. Test against the vendor’s sandbox identity catalogue, exercising both success and failure paths. Run a small real-customer pilot before full traffic ramp.
How long does KYC integration take?
A clean API-first integration typically takes two to six engineering-weeks. SDK-embedded integration runs one to three engineering-weeks for a single platform (iOS or Android). Hosted-flow integration runs one to two engineering-weeks. Add roughly one to two weeks for testing, sandbox-to-production cutover, and the first real-customer pilot.
What is the difference between KYC API and KYC software?
KYC software is the broader vendor product: the orchestration layer, the workflow, the case management, and the underlying capabilities. The KYC API is the developer interface to that software, the HTTPS endpoints the institution calls to trigger verification. Software is what you buy. The API is how you use it.
Should I build or buy KYC?
For almost every institution, buy. Building requires multi-year programme investment in OCR, biometrics, sanctions data feeds, and ongoing regulatory adaptation that the institution’s roadmap rarely supports. Buying lets the institution focus engineering on the orchestration, integration, and customer experience layers where it can actually differentiate.
What are the best KYC integration providers?
The category leaders include HyperVerge (India-first, APAC and US coverage), Jumio (global, especially crypto), Onfido (UK and EU), Sumsub (crypto and iGaming), and Veriff (mobility and consumer). The right answer depends on sector, geography, and verification volume. The integration model and stack-specific pattern decide the production outcome more than the headline vendor choice.
How does KYC integrate with a CRM?
The standard pattern fires KYC verification from the lead-conversion or account-creation trigger, with the verification result written back to the CRM’s customer record as enumerated status fields plus the verification timestamp and the provider’s session ID. Salesforce Financial Services Cloud and Microsoft Dynamics 365 both support this through their respective customisation frameworks.
What security requirements apply to KYC integration?
TLS in transit (mTLS where risk warrants), webhook signature verification with timing-safe comparison, encrypted storage at rest with key rotation, Aadhaar masking for Indian customers, and PII redaction in non-production environments. Data residency obligations under GDPR, DPDP Act, and equivalent frameworks must be designed in from day one.
How do I handle KYC re-screening events?
Implement the webhook handler for ongoing-monitoring events from day one. The vendor will POST events when sanctions hits, adverse media flags, or change-of-circumstance triggers occur for previously verified customers. The handler should normalise the event, route it to the institution’s compliance review queue, and update the customer record with the new status. Skipping this is one of the most common integration anti-patterns.
What is a webhook signature and why does it matter?
A webhook signature is an HMAC computed by the vendor over the webhook payload using a shared secret, included in the request headers. The receiving handler must recompute the HMAC and compare against the header value before trusting the payload. Without signature verification, any party that knows the webhook URL can post arbitrary payloads, creating a replay-attack vector and an audit-trail integrity failure.
