KYC (Know Your Customer) API

Sznd provides KYC (Know Your Customer) verification through our API to help you onboard and verify your customers. You can either generate a KYC link for customers to complete verification themselves, or submit KYC documents directly through our API.

Overview

KYC verification is required for customers to access certain features including deposits, withdrawals, and currency exchanges. Our KYC process integrates with Footprint, a third-party KYC provider, to securely verify customer identities and documents.

Two Methods for KYC Verification

Method 1: Generate KYC Link (Customer Self-Service)

Generate a KYC onboarding link that you can pass to your customers. They complete the verification process themselves through Footprint's secure interface.

Method 2: Submit KYC via API (Programmatic)

Submit KYC documents and customer information directly through our API using a Footprint token.

Method 1: Generate KYC Link

Generate a KYC onboarding link for your customers to complete verification. This is useful when you want customers to handle their own KYC submission.

Option A: During User Registration

When registering a new user, a KYC link is automatically generated if the email is not verified.

Endpoint: POST /api/v1/auth/register

Authentication: Not required

Request Body:

{
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "password": "SecurePassword123!",
  "date_of_birth": "1990-01-15",
  "phone_number": "+1234567890",
  "country_code": "US",
  "user_type": "CUSTOMER"
}

Response (201 Created):

{
  "message": "User created successfully",
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "CUSTOMER"
  },
  "onboarding_data": {
    "link": "https://onboarding.footprint.com/session/abc123",
    "token": "fp_token_abc123def456",
    "expires_at": "2024-01-18T10:30:00Z"
  }
}

The onboarding_data field contains:

• link - URL to send to your customer for KYC completion
• token - Footprint token ID (save this for later use)
• expires_at - When the link expires (typically 3 days)

Option B: Resume Onboarding for Existing User

If a user already exists but hasn't completed KYC, you can generate a new onboarding link.

Endpoint: POST /api/v1/auth/users/{id}/resume-onboarding

Authentication: Required (JWT Bearer token)

Path Parameters:

• id (UUID) - User ID

Response (200 OK):

{
  "expires_at": "2024-01-18T10:30:00Z",
  "link": "https://onboarding.footprint.com/session/resume_abc123",
  "token": "fp_token_resume_abc123def456"
}

Example: Register User and Get KYC Link

curl -X POST /api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "password": "SecurePassword123!",
    "date_of_birth": "1990-01-15",
    "phone_number": "+1234567890",
    "country_code": "US",
    "user_type": "CUSTOMER"
  }'

Example: HTTP Request

POST /api/v1/auth/register HTTP/1.1
Host: api.sznd.app
Content-Type: application/json

{
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "password": "SecurePassword123!",
  "date_of_birth": "1990-01-15",
  "phone_number": "+1234567890",
  "country_code": "US",
  "user_type": "CUSTOMER"
}

Example: Resume Onboarding

curl -X POST /api/v1/auth/users/{user_id}/resume-onboarding \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Example: HTTP Request

POST /api/v1/auth/users/{user_id}/resume-onboarding HTTP/1.1
Host: api.sznd.app
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Method 2: Submit KYC via API

Submit KYC documents and customer information programmatically using a Footprint token. This method is useful when you've already collected KYC information from your customers.

Onboard Business Contact

Endpoint: POST /api/v1/business/contact/onboard

Authentication: Required (JWT Bearer token)

Request Body:

{
  "token_id": "fp_token_abc123def456"
}

Parameters:

• token_id (string, required) - Footprint token ID from the KYC session

Response (200 OK):

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "email": "business.contact@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone_number": "+2348012345678",
  "role": "CUSTOMER",
  "user_type": "BUSINESS",
  "user_status": "ACTIVE",
  "kyc_status": "APPROVED",
  "date_of_birth": "1990-01-01T00:00:00Z",
  "country_code": "CA",
  "address_line_1": "123 Example Street",
  "city": "Toronto",
  "postal_code": "A1B2C3",
  "created_at": "2025-01-30T12:20:15Z",
  "updated_at": "2025-01-30T12:20:15Z"
}

Example: Submit KYC via API

curl -X POST /api/v1/business/contact/onboard \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "token_id": "fp_token_abc123def456"
  }'

Example: HTTP Request

POST /api/v1/business/contact/onboard HTTP/1.1
Host: api.sznd.app
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "token_id": "fp_token_abc123def456"
}

Supported Identity Documents

The following government-issued identity documents are accepted for KYC verification:

Primary Identity Documents

1. Passport

   • Valid passport from any country
   • Must include front page with photo and personal details
   • Must be current and not expired

2. National ID Card

   • Government-issued national identification card
   • Must include front and back images
   • Must be current and not expired
   • Examples: Nigerian National ID, US State ID, etc.

3. Driver's License

   • Valid driver's license from any country
   • Must include front and back images
   • Must be current and not expired

4. Residence Permit

   • Valid residence permit or visa
   • Required for non-citizens in certain jurisdictions
   • Must be current and not expired

5. Proof of Address (Additional Document)

   • Utility bill (electricity, water, gas)
   • Bank statement
   • Government-issued document with address
   • Must be dated within the last 3 months

Document Requirements

All identity documents must meet the following requirements:

• Validity: Documents must be current and not expired (unless expiry date is not applicable)
• Clarity: Images must be clear, legible, and in good condition
• Completeness: Both front and back images are required (where applicable)
• Format: Documents must be submitted as high-quality images (minimum 20KB file size)
• Authenticity: Documents must be genuine and not altered or tampered with

Document Image Specifications

• Format: JPEG, PNG, or PDF
• Minimum Size: 20KB per image
• Minimum Dimensions: Must meet minimum resolution requirements for verification
• Quality: Clear, readable text and visible photo
• Orientation: Correctly oriented (not rotated)

Personal Data Collected

During the KYC verification process, the following personal information is collected:

Required Information

Address Information

The following address details are collected:

• Street Address (Line 1) - Primary street address (required)
• Street Address (Line 2) - Apartment, suite, or unit number (optional)
• City - City name (required)
• State/Province - State or province (if applicable)
• Postal Code - ZIP code or postal code (required)
• Country - Country of residence (required, ISO country code)

Optional Information

Document-Specific Information

For each identity document submitted, the following information is collected:

• Document Type - Type of document (Passport, National ID, Driver's License, etc.)
• Document Number - Unique identifier on the document (if available)
• Issuing Country - Country that issued the document
• Issue Date - Date when the document was issued
• Expiry Date - Date when the document expires (if applicable)
• Front Image - Image of the front side of the document (base64 encoded)
• Back Image - Image of the back side of the document (where applicable, base64 encoded)

KYC Verification Flow

Using KYC Link (Method 1)

1. Generate Link - Call registration or resume onboarding endpoint
2. Send Link to Customer - Pass the link from the response to your customer
3. Customer Completes KYC - Customer completes verification on Footprint's secure interface
4. Get Token - Save the token from the response
5. Onboard Contact - Use the token to onboard the contact via /business/contact/onboard

Using API Submission (Method 2)

1. Get Footprint Token - Obtain a Footprint token from your KYC provider integration
2. Submit Token - Call /business/contact/onboard with the token
3. Receive User - Get back the user object with KYC status

KYC Status

After onboarding, you can check the KYC status in the user object:

• APPROVED - KYC verification completed successfully
• PENDING - Verification is in progress
• REJECTED - Verification failed (check for additional details)
• NOT_STARTED - KYC verification has not been initiated

Check KYC Status

// After onboarding, check the user's KYC status
const user = await onboardContactWithKYCToken(tokenId, accessToken);
 
if (user.kyc_status === 'APPROVED') {
  console.log('Customer is verified and ready to transact');
} else if (user.kyc_status === 'PENDING') {
  console.log('KYC verification is in progress');
} else if (user.kyc_status === 'REJECTED') {
  console.log('KYC verification failed - customer needs to resubmit');
}

Error Handling

Common Errors

Error Response Format

{
  "error": "Token is required",
  "message": "The token_id field is required for onboarding"
}

Best Practices

1. Store Tokens Securely - Save Footprint tokens securely for later use
2. Handle Expiration - KYC links expire (typically 3 days). Generate new links if needed
3. Monitor Status - Regularly check KYC status after onboarding
4. Error Handling - Implement proper error handling for failed verifications
5. Retry Logic - Implement retry logic for transient failures
6. Webhook Integration - Set up webhooks to receive KYC status updates automatically

Webhook Integration

Consider setting up webhooks to receive real-time KYC status updates. This allows you to:

• Get notified when KYC verification completes
• Handle status changes automatically
• Update your system when verification fails

See the Webhooks documentation for more information.

Compliance and Regulations

Our KYC process complies with:

• Anti-Money Laundering (AML) regulations
• Know Your Customer (KYC) requirements
• Customer Due Diligence (CDD) standards
• Financial Action Task Force (FATF) recommendations
• Local regulatory requirements in jurisdictions where we operate

Next Steps

• Authentication - Learn about API authentication
• Webhooks - Set up webhooks for KYC status updates
• Quotes API - Create quotes for verified customers