Skip to main content

​
Overview

The KYC (Know Your Customer) module provides identity verification services to ensure compliance with regulatory requirements. Bloque uses AMLBOT as the verification provider to perform identity checks.

​
What is KYC?

KYC verification confirms a user’s identity by validating government-issued documents and performing anti-money laundering (AML) checks. This is required for financial services and regulated industries.

​
KYC Client

Access KYC functionality through the compliance client: 
const kyc = bloque.compliance.kyc;

​
Start KYC Verification

Initiate a KYC verification process for a user:
compliance/src/kyc/types.ts
interface KycVerificationParams {
  urn: string;          // Identity URN to verify
  webhookUrl?: string;  // Optional webhook for status updates
}

​
Example: Basic KYC Verification

const verification = await bloque.compliance.kyc.startVerification({
  urn: 'did:bloque:origin:ethereum-mainnet:0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6'
});

console.log('Verification URL:', verification.url);
console.log('Status:', verification.status);
Direct the user to verification.url to complete their KYC verification.

​
Example: With Webhook Notifications

const verification = await bloque.compliance.kyc.startVerification({
  urn: userUrn,
  webhookUrl: 'https://api.example.com/webhooks/kyc'
});

console.log('Verification started');
console.log('Redirect user to:', verification.url);
You’ll receive webhook notifications when the verification status changes.

​
Get Verification Status

Check the current status of a KYC verification: 
const status = await bloque.compliance.kyc.getVerification({
  urn: userUrn
});

console.log('Status:', status.status);
console.log('Verification URL:', status.url);

if (status.completedAt) {
  console.log('Completed at:', status.completedAt);
}

​
Verification Response

compliance/src/kyc/types.ts
interface KycVerificationResponse {
  status: 'awaiting_compliance_verification' | 'approved' | 'rejected';
  url: string;              // URL for user to complete verification
  completedAt: string | null;  // ISO 8601 timestamp when completed
}

​
Verification Status Values

StatusDescription
awaiting_compliance_verificationVerification is in progress or not yet started
approvedUser has been successfully verified
rejectedVerification was rejected (failed checks)

​
Verification Flow

1

Register Identity

First, register the user’s identity using the Identity Origins API:
const registration = await bloque.identity.origins.register(
  alias,
  origin,
  registerParams
);
2

Start KYC Verification

Initiate KYC verification for the registered identity:
const verification = await bloque.compliance.kyc.startVerification({
  urn: registration.urn,
  webhookUrl: 'https://api.example.com/webhooks/kyc'
});
3

Redirect User

Direct the user to the verification URL to complete the process:
// In your web app
window.location.href = verification.url;
4

Monitor Status

Check verification status or wait for webhook notifications:
const status = await bloque.compliance.kyc.getVerification({
  urn: userUrn
});

if (status.status === 'approved') {
  console.log('User verified!');
}

​
Webhook Integration

Receive real-time updates when verification status changes: 
// Express.js webhook endpoint example
app.post('/webhooks/kyc', async (req, res) => {
  const { urn, status, completedAt } = req.body;
  
  console.log('KYC status update:', { urn, status, completedAt });
  
  if (status === 'approved') {
    // Enable user account features
    await enableUserAccount(urn);
  } else if (status === 'rejected') {
    // Notify user of rejection
    await notifyUserRejection(urn);
  }
  
  res.status(200).send('OK');
});
Always validate webhook signatures in production to ensure requests are authentic.

​
Complete Example

// 1. Register user identity
const registration = await bloque.identity.origins.register(
  '[email protected]',
  'bloque-email',
  {
    type: 'individual',
    profile: {
      firstName: 'John',
      lastName: 'Doe',
      email: '[email protected]',
      birthdate: '1990-01-15',
      city: 'New York',
      state: 'NY'
    },
    assertionResult: emailAssertion
  }
);

// 2. Get the user's identity
const me = await bloque.identity.me();

// 3. Start KYC verification
const verification = await bloque.compliance.kyc.startVerification({
  urn: me.urn,
  webhookUrl: 'https://api.example.com/webhooks/kyc'
});

// 4. Redirect user to verification
console.log('Complete verification at:', verification.url);

// 5. Check status later
setTimeout(async () => {
  const status = await bloque.compliance.kyc.getVerification({
    urn: me.urn
  });
  
  console.log('Current status:', status.status);
  
  if (status.status === 'approved') {
    console.log('Verification completed at:', status.completedAt);
  }
}, 300000); // Check after 5 minutes

​
Verification Provider

Bloque uses AMLBOT as the KYC verification provider. AMLBOT performs:
  • Identity document verification
  • Biometric facial recognition
  • Anti-Money Laundering (AML) checks
  • Sanctions list screening
  • Politically Exposed Person (PEP) checks

​
Verification Levels

Currently, Bloque supports:
  • Basic KYC - Standard identity verification with document upload and facial recognition
Additional verification levels may be added in the future.

​
Error Handling

import { 
  BloqueValidationError, 
  BloqueNotFoundError 
} from '@bloque/sdk-core';

try {
  const verification = await bloque.compliance.kyc.startVerification({
    urn: userUrn,
    webhookUrl: invalidUrl // Invalid URL format
  });
} catch (error) {
  if (error instanceof BloqueValidationError) {
    console.error('Invalid parameters:', error.message);
  } else if (error instanceof BloqueNotFoundError) {
    console.error('Identity not found:', error.message);
  }
}

​
Best Practices

Always check KYC status before allowing users to:
  • Create financial accounts
  • Perform large transactions
  • Access regulated features
const status = await bloque.compliance.kyc.getVerification({ urn: userUrn });

if (status.status !== 'approved') {
  throw new Error('KYC verification required');
}
Don’t poll for status updates. Use webhooks to receive real-time notifications:
const verification = await bloque.compliance.kyc.startVerification({
  urn: userUrn,
  webhookUrl: 'https://api.example.com/webhooks/kyc'
});
Provide clear messaging when verification is rejected:
if (status.status === 'rejected') {
  // Inform user and provide support contact
  await sendEmail(user.email, {
    subject: 'Verification Status',
    body: 'Your verification was not approved. Please contact support.'
  });
}
  • Use HTTPS for webhook URLs
  • Validate webhook signatures
  • Implement rate limiting
  • Log all webhook events for audit trails
KYC verification is required for creating financial accounts (cards, bank accounts) and performing certain transactions.

Identity

Register identities before KYC

Accounts

Create accounts after verification

Build docs developers (and LLMs) love

Get started for freeTalk to us