KYC Document Upload API

info

The KYC Document Upload API enables merchants and account holders to securely upload Know-Your-Customer (KYC) documents for compliance and verification purposes. This API supports uploads of various document types optimized for both individual and corporate account holders.

1.0 AUTHORIZATION

Authorization to the APIs below requires an access token. To get more info on how to generate this access token, click on Generating Access Token

2.0 BASE URL

All requests to the KYC Document Upload API must be done using the web API URL below.

Test Environment: https://api-devapps.vfdbank.systems/vtech-kyc/api/v2/kyc

LIVE Environment: https://api-apps.vfdbank.systems/vtech-kyc/api/v2/kyc

3.0 HOW TO USE THE APIS

Below are the steps involved to upload KYC documents:

1. Ensure you have a valid customer account number
2. Determine which documents are required based on your account type (individual or corporate)
3. Prepare the required documents in the expected format (base64 encoded images or structured data)
4. Call the BULK UPLOAD KYC BUNDLE endpoint with your accountNo and the document fields
5. A confirmation response is returned with upload details and resource identifiers

Note: Include only the document fields required for your use case.

3.1 BULK UPLOAD KYC BUNDLE

API Context: /bulk-upload/kyc-bundle

Description: This endpoint enables upload of KYC documents for customer accounts. The API validates your account information and verifies document types against your account classification (individual or corporate). API METHOD: POST

REQUEST HEADERS

Key	Value
AccessToken	{{token}}
Content-Type	application/json

3.1.1 Sample Request Payload for Individual Accounts

Sample Request (Individual Account - Utility Bill)

{
  "accountNo": "1234567890",
  "documentType": "utilityBill",
  "utilityBill": {
    "base64Image": "data:image/png;base64,..."
  }
}

Sample Request (Individual Account - Account Opening Data)

{
  "accountNo": "1234567890",
  "documentType": "accountOpeningData",
  "accountOpeningData": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phoneNumber": "08012345678",
    "bvn": "12345678901"
  }
}

Note: Include any additional key-value pairs relevant to your account opening information. The fields shown are examples; you can submit any custom fields needed.

Sample Request (Individual Account - Identity Documents)

{
  "accountNo": "1234567890",
  "documentType": "identityDocuments",
  "identityDocuments": [
    {
      "identityType": "NIN",
      "frontImage": {
        "base64Image": "data:image/png;base64,..."
      },
      "backImage": {
        "base64Image": "data:image/png;base64,..."
      }
    }
  ]
}

3.1.2 Sample Request Payload for Corporate Accounts

Sample Request (Corporate Account - Business Registration Document)

{
  "accountNo": "9876543210",
  "documentType": "cacCertificate",
  "cacCertificate": {
    "base64Image": "data:image/png;base64,..."
  }
}

Sample Request (Corporate Account - KYC of Signatories)

{
  "accountNo": "9876543210",
  "documentType": "signatories",
  "signatories": [
    {
      "name": "Jane Director",
      "bvn": "99988877766",
      "address": {
        "base64Image": "data:image/png;base64,..."
      },
      "validId": {
        "identityType": "Driver License",
        "frontImage": {
          "base64Image": "data:image/png;base64,..."
        },
        "backImage": {
          "base64Image": "data:image/png;base64,..."
        }
      }
    }
  ]
}

Sample Request (Corporate Account - Beneficial Owners Details)

{
  "accountNo": "9876543210",
  "documentType": "beneficialOwners",
  "beneficialOwners": [
    {
      "ownerName": "Test Holdings Ltd",
      "cacCertificate": {
        "base64Image": "data:image/png;base64,..."
      },
      "statusReport": {
        "base64Image": "data:image/png;base64,..."
      },
      "memorandumArticles": {
        "base64Image": "data:image/png;base64,..."
      }
    }
  ]
}

Request Parameters

Field	Description	Status
accountNo	The customer's account number	Mandatory
documentType	The primary document type being uploaded	Mandatory
Document Fields	One or more document fields as shown below	At least one required

Document Field Patterns:

1. Simple Document Type (most common)

   • Structure: { "base64Image": "data:image/png;base64,..." }
   • Applied to: utilityBill, cacCertificate, memorandumArticles, statusReport, boardResolution, tin, companyProofOfAddress, operatingLicense, scumlCertificate, addressVisitationReport, sanctionPepReport

2. Account Opening Data (flexible key-value structure)

   • Customers can submit any key-value pairs relevant to their account opening information
   • Common fields for individuals: firstName, lastName, otherNames, dateOfBirth, gender, email, phoneNumber, address, state, city, nationality, nin, bvn, occupation
   • Common fields for corporates: businessName, businessType, rcNumber, taxId, email, phoneNumber, address, state, city, nationality
   • Include only the fields applicable to your use case; field selection is not restricted to the list above

3. Identity Documents (array structure)

   • Array of identity objects with identityType, frontImage, and optional backImage
   • Supported types: BVN, International Passport, Driver License, National ID, etc.

4. Signatories (corporate - array structure)

   • Array of signatory objects with name, bvn, address proof, and valid id
   • Each signatory includes identity documents

5. Beneficial Owners (corporate - array structure)

   • Array of beneficial owner objects with ownerName and supporting documents (cacCertificate, statusReport, memorandumArticles)

Supported Document Types for Individual Accounts

Document Type	Description
utilityBill	Utility bill (electricity, water, gas)
accountOpeningData	Form with key account creation information such as customer name, BVN/NIN, phone, email, and residential address e.t.c.
identityDocuments	Government-issued ID documents

Supported Document Types for Corporate Accounts

Document Type	Description
utilityBill	Utility bill (electricity, water, gas)
accountOpeningData	Form with key account creation information such as business name, business registration, phone, email, and company address e.t.c.
identityDocuments	Government-issued ID documents
cacCertificate	CAC (Corporate Affairs Commission) Certificate
memorandumArticles	Memorandum and Articles of Association
statusReport	Company status report
boardResolution	Board resolution authorizing account
tin	Tax Identification Number certificate
companyProofOfAddress	Company proof of address or business premises
operatingLicense	Operating license or business permit
scumlCertificate	SCUML certificate (Anti-money laundering)
addressVisitationReport	Address visitation report
sanctionPepReport	Sanctions and PEP (Politically Exposed Person) report

Sample Response - Success

{
  "status": "00",
  "message": "Document upload successful.",
  "data": {
    "uploadResults": [
      {
        "documentType": "UTILITY_BILL",
        "status": "SUCCESS"
      }
    ]
  }
}

Response Parameters

Field	Description
status	Response status code ("00" indicates success)
message	Response message
uploadResults	Array containing the results of each uploaded document
documentType	The type of document uploaded (uppercase with underscores)
status	Status of the individual document upload (SUCCESS/FAILED)

Error Response - Account Not Found

{
  "status": "01",
  "message": "No client found for account number."
}

Error Response - Missing Required Fields

{
  "status": "98",
  "message": "accountNo is mandatory."
}

Error Response - Invalid Document for Account Type

{
  "status": "98",
  "message": "Document type not allowed for this account type."
}

Error Response - Document Upload Failed

{
  "status": "99",
  "message": "Document upload failed"
}

Error Response - Service Unavailable

{
  "status": "500",
  "message": "Internal server Error"
}

4.0 API RESPONSE CODES

Status Code	Description	Action Required
00	Success	None - operation completed
01	Account not found	Verify account number
98	Validation failed	Check document type validity
99	Document upload failed	Retry upload
500	Internal server error	Contact support