KES Virtual Account

This guide explains how to integrate static KES (Kenyan Shilling) Virtual Accounts via API. These allow businesses to receive KES payments, settled automatically into the merchant's wallet.

⚠️ Important Setup Notice

• KES VA setup requires manual onboarding of your main account by Fincra.
• Once approved, you can create sub-accounts via the API.
• Onboarding typically takes up to 48 hours (based on document completeness).

🔐 Authentication

Your API keys are available on the dashboard under My Acc > Acc Settings > API Keys.

🏦 Supported Bank

As more banks are supported, this guide will be updated.

🔤 Basic Information Required

For Sole Proprietorship:

• Business Name
• Full Name (Proprietor)
• Date of Birth (DD/MM/YYYY)
• Gender
• Business Industry
• Business Address
• Next of Kin Full Name & Phone (with country code)
• Relationship to Next of Kin

For LLCs or Partnerships:

• Business Name
• Operating Mode (e.g. any two to sign)
• Business Industry
• Business Address

📄 Required KYB Documents

Limited Liability Company

Sole Proprietorship

📎

Submit documents in PDF or JPEG format. Notarization is required for foreign entities.

📝 Submit Onboarding Request

Send your onboarding request to: [email protected]

Include:

• Subject: <Your Business Name> - Request for KES VA
• Body: Basic information listed above
• Attachments: Required KYB documents

🧾 Naming Convention

• Your main VA name is your business name.
• Sub-accounts are labeled as: BusinessName_SubAccountName

🔄 Creating Sub Virtual Accounts via API

Request Parameters

Individual Account

Corporate Account

Sample Request (Corporate)

{
  "accountType": "corporate",
  "currency": "KES",
  "KYCInformation": {
    "businessName": "Testoma"
  },
  "merchantReference": "merchant-8jf9j00",
  "phoneNumber": "+254206786543"
}

Sample Request (Individual)

{
  "accountType": "individual",
  "currency": "KES",
  "KYCInformation": {
    "firstName": "Hi",
    "lastName": "Corporation"
  },
  "merchantReference": "merchant-6d78f9j00",
  "phoneNumber": "+254209876543"
}

Sample Response

{
  "success": true,
  "message": "A KES virtual account has been created for you",
  "data": {
    "accountInformation": {
      "accountNumber": "7003000100286",
      "accountName": "Fincra_testoma",
      "reference": "2bd48a28-0199-4de8-bac0-ae998efaad9e",
      "bankName": "Choice Bank"
    },
    "currency": "KES",
    "accountType": "corporate",
    "entityType": "main_account",
    "isPermanent": true,
    "isActive": true,
    "isSuspended": false
  }
}

ℹ️

Any businessName in your request is appended to your onboarded name.

• Main: Fincra Technologies Limited
• Sub: Merchant 1
• Final: Fincra Technologies Limited_Merchant 1

📡 Webhook Notification (Sample)

{
  "event": "collection.successful",
  "data": {
    "virtualAccountType": "additional",
    "senderAccountName": "Sender Name",
    "amountReceived": 5580,
    "amountExpected": 6000,
    "varianceType": "underpayment",
    "fee": 420,
    "message": "INCORRECT_AMOUNT",
    "status": "successful",
    "reference": "48173-2ff9-4ref-85b4-2e5ed4429e3"
  }
}

🔗 How to Validate Webhooks

📥 Retrieve Account Info

GET {{base_url}}/profile/virtual-accounts/<virtual_account_id>

Returns full account details for a specific virtual account.

📃 List All Virtual Accounts

GET {{base_url}}/profile/virtual-accounts/?currency=KES

Returns a list of all your created KES virtual accounts.

💳 Funding Virtual Accounts

Refer to: Funding a Virtual Account →