GHS Virtual Account

This guide provides instructions for integrating static GHS (Ghana Cedi) Virtual Accounts via API. Merchants can create permanent virtual accounts to receive GHS payments from customers. Funds do not sit in the virtual account directly — the VA acts as a collection reference mapped to the merchant’s GHS wallet.


📌 Key Points

  • Real-time issuing: Both individual and corporate GHS virtual accounts are issued instantly.
  • Settlement: Funds are settled into the merchant’s GHS wallet.
  • Authentication: Uses API keys in the header (not standard Bearer token).

🔐 Authentication

TypeDetails
Auth TypeNo Auth
Headerapi-key
Content-Typeapplication/json
API KeysAvailable under My Acc > Acc Settings > API Keys on your dashboard

🏦 Supported Bank

Bank NameSwift CodeNotes
Affinity BankAPFDUS44XXXDefault issuing institution


⚙️ Request Parameters

📁 Individual Virtual Account

FieldRequiredTypeDescription
currencyYesstringMust be "GHS"
accountTypeYesstringMust be "individual"
KYCInformation.firstNameYesstringCustomer’s first name
KYCInformation.lastNameYesstringCustomer’s last name
KYCInformation.emailYesstringCustomer’s email
phoneNumberNostringBusiness phone in international format (e.g. +233...)
merchantReferenceNostringUnique reference on your system

📁 Corporate Virtual Account

FieldRequiredTypeDescription
currencyYesstringMust be "GHS"
accountTypeYesstringMust be "corporate"
KYCInformation.businessNameYesstringMerchant’s business name
KYCInformation.emailYesstringBusiness email
phoneNumberNostringBusiness phone in international format
merchantReferenceNostringUnique reference on your system

🗂️ Sample Requests

✅ Corporate

{
  "accountType": "corporate",
  "currency": "GHS",
  "KYCInformation": {
    "businessName": "Oma's Empire",
    "email": "[email protected]"
  },
  "merchantReference": "merchant-8jdf9j00",
  "phoneNumber": "+233206786543"
}

✅ Individual

{
  "accountType": "individual",
  "currency": "GHS",
  "KYCInformation": {
    "firstName": "Hi",
    "lastName": "Corporation",
    "email": "[email protected]"
  },
  "merchantReference": "merchant-6d78f9j00",
  "phoneNumber": "+233209876543"
}

📥 Sample Response

{
  "success": true,
  "message": "A GHS virtual account has been created for you",
  "data": {
    "status": "approved",
    "isActive": true,
    "accountNumber": "7003000100286",
    "merchantReference": "merchant-8j9j00",
    "KYCInformation": {
      "businessName": "Oma's Empire",
      "email": "[email protected]"
    },
    "accountInformation": {
      "accountNumber": "7003000100286",
      "accountName": "Oma's Empire",
      "reference": "2bd48a28-0199-4de8-bac0-ae998efaad9e",
      "bankName": "Affinity"
    },
    "_id": "6865acbe26869a007121d7f5b",
    "business": "64493f61864cdb7aab9bb4576",
    "currency": "GHS",
    "accountType": "corporate",
    "entityType": "main_account",
    "currencyType": "fiat",
    "createdAt": "2025-07-02T22:03:42.724Z",
    "updatedAt": "2025-07-02T22:03:42.724Z"
  }
}

Notes:

  • _id: Unique virtual account ID.
  • business: Your Business ID.

📡 Webhook Notifications

You’ll receive a webhook event for every collection received.

✅ Sample Webhook

{
  "event": "collection.successful",
  "data": {
    "business": "6***********3",
    "virtualAccount": "6******8*****4",
    "virtualAccountType": "main",
    "sessionId": "I34500",
    "senderAccountName": "Sender Name",
    "senderAccountNumber": "110*******63",
    "senderBankDetails": {
      "bankName": "CAL BANK",
      "bankCode": null,
      "swiftCode": null,
      "bic": null
    },
    "sourceCurrency": "GHS",
    "destinationCurrency": "GHS",
    "sourceAmount": 3000,
    "destinationAmount": 3000,
    "description": "Hello World",
    "amountReceived": 2730,
    "fee": 30,
    "customerName": "Customer Name",
    "settlementDestination": "wallet",
    "status": "successful",
    "initiatedAt": "2025-07-02T21:56:02.945Z",
    "createdAt": "2025-07-02T21:56:02.999Z",
    "updatedAt": "2025-07-02T21:56:02.999Z",
    "reference": "48173-2ff9-4ref-85b4-2e5ed4429e3",
    "merchantReference": "2456552"
  }
}

📖 How to validate webhooks →


📂 Retrieve Virtual Account Details

GET

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

Returns details of a single virtual account.


📃 Retrieve All Virtual Accounts

GET

{{base_url}}/profile/virtual-accounts/?currency=GHS

Returns all GHS virtual accounts you’ve created.


💳 Fund Your Virtual Account

Refer to: Funding a Virtual Account →


📌

For updates on changes to the Virtual Account endpoint, watch your email.