LogoLogo
  • Welcome!
  • Integrating Klasha
    • Getting Started
    • Prerequisites
    • Integration Checklist
    • Wrap Up
  • Overview
    • Introduction
    • Parameters
    • Token Generation
    • Errors
    • Countries & Payment Methods
  • Accepting Payments
    • Test Payments
    • Payments API
      • Mobile money
      • USSD
    • Payment Link
      • Dashboard
      • Payment Link API
    • Klasha Inline
    • HTML Checkout
  • PLUGINS AND SDKS
    • Plugins
    • Mobile SDKs
    • Web SDKs
  • MISC
    • Transaction Status
    • Webhook
    • API Status
  • Features
    • One-time Payments
    • Recurrent Payment
  • Transfers
    • Payout
      • ZAR Payout(new encryption)
      • KES Payout(new encryption)
      • ZMW Payout(new encryption)
      • TZS Payout(new encryption)
      • CNY Payout(new encryption)
    • Klasha Wire API
    • Swap API
    • Currency Coverage
  • Bank Account Collection
    • Virtual Account Creation
    • VA balance and statement
    • Business Identification Service
Powered by GitBook
On this page
  • Summary
  • Coverage
  • Initiate VA creation
  • create a virtual account
  • Requery
  • Polling transaction status
  1. Bank Account Collection

Virtual Account Creation

PreviousCurrency CoverageNextVA balance and statement

Last updated 2 months ago

Summary

Create Virtual Accounts on demands, receive funds from customers via Virtual Account Number and get notification on Virtual Accounts usage.

Dedicated Virtual Accounts (DVAs) is a service that lets you create Nigerian virtual accounts for your customers. These accounts allow your customers to receive payment from their customers.

When you create a Dedicated Virtual Account (DVA) for a customer, all bank transfers to that account will automatically be recorded as transactions from that customer.

Coverage

  • NGN

Integration steps

You can generate a VA and start receiving money in 3 easy steps:

  1. Prepare payload (payload includes: first name, last name, BVN, and email)

  2. Initiate VA creation (encrypting payload)

  3. Get instant response


Before you begin!

  • to the Postman collection

  • Find your keys on the Klasha Dashboard → Settings → Generate API Keys ()

  • Klasha Dashboard, Generate API Keys page

Initiate VA creation

create a virtual account

POST {{env_url}}/wallet/virtual/v3/business/create/account

Encrypt the plain request body using the encryption algorithm specified above. Set the encrypted data to the message as shown below. You are required to set the x-auth-token and Authorization in the headers.

Headers

Key
Value

x-auth-token

Your merchant public key

Authorization

Bearer <token here>

Request Body (encrypted)

{
   "message": "encrypted-message"
}

The result of the encryption of the payload that we specified has to be used with the Create virtual account endpoint as shown below:

Request Body (plain)

(Individual)
{
   "firstName": "John",
   "lastName": "Doe",
   "bvn": "22222222222",
   "email": "test@klasha.com"
}
(Business)
{
   "bvn": "22222222222",
   "email": "test@klasha.com"
}
Name
Type
Description

firstName*

String

John

lastName*

String

Doe

bvn*

22222222222

email*

String

test@klasha.com

When a VA creation is initiated, processing could take a few seconds. These are sample responses you will get below:

{
    "id": 218,
    "walletId": null,
    "accountNumber": "8574578073",
    "bankName": "WEMA BANK",
    "orderRef": "fOeatZO40PEJzeiPvq8q",
    "txRef": "klasha-virtual-account-banktransfer-Steph and sons-133",
    "flwRef": "URF_G6Ie8ZP9GZ5hAZk8z6fZ",
    "userId": null,
    "businessId": 133,
    "bankCode": null,
    "enabled": true,
    "accountName": "Stephen Ojerinde",
    "email": "test@steph.com",
    "profileHash": "hwKpOI9+kZR/fFy7hLOpcQ==",
    "createdAt": "2023-07-07 00:42:45",
    "updatedAt": "2023-07-07 00:42:45"
}

{
    "message": "There is no identity available for this bvn.",
    "error": "Operation not allowed"
}
{
    "message": "Bvn name mismatch.",
    "error": "Operation not allowed"
}

Requery

GET {{env_url}}/wallet/virtual/v2/account/{{email}}

In case of network downtime or failures during VA creation, the virtual account can be re-queried with the user’s email. This can be fetched using the Requery with email API on the Postman collection.

Headers

Key
Value

Authorization

Bearer <token here>

[
    {
        "accountNumber": "8573777620",
        "bankName": "WEMA BANK",
        "orderRef": "HsKRPDlemp7XBKvgO1HE",
        "txRef": "klasha-fund-wallet-banktransfer-steph-AJDcN6app",
        "flwRef": "URF_1Qw8TF2ZN1KkIdsqyHYI",
        "businessId": 5,
        "enabled": true,
        "accountName": "Forrest Green",
        "email": "test@klasha.com",
        "createdAt": "2023-07-04 17:02:59",
        "updatedAt": "2023-07-04 17:02:59"
    }
]
Transaction Webhook

When payments are received from your users, we would send a webhook with the details of the transaction to your callback URL.

{
  "data": {
    "createdAt": "2023-07-14T19:28:18.585",
    "narration": "Bank Transfer",
    "destinationCurrency": "NGN",
    "sourceAmount": 2000,
    "sourceCurrency": "NGN",
    "virtualAccount":"0987654321",
    "tnxRef": "reference_322123243",
    "status": "successful",
    "destinationAmount": 2000,
    "originatorAccountName":"Stephen Oj",
    "bankName": "Access Bank",
    "originatorAccountNumber":"1234456211",
    "customer": {
      "id": 53603,
      "name": "Last Name",
      "email": "test@steph.com",
      "phone": null,
      "createdAt": "2023-07-04 20:11:05",
      "updatedAt": "2023-07-04 20:11:05"
    }
  },
  "event": "charge.completed"
}

Polling transaction status

POST {{env_url}}/nucleus/tnx/collection/status

To know the status of a transaction, you can fetch the transaction using the Transaction Status API on the Postman collection. Make use of the session id received from the bank. See an example below:

Request Body

Name
Type
Description

gateRef*

String

10043599483902847574821

{
    "destinationCurrency": "NGN",
    "sourceAmount": 2500.000000,
    "sourceCurrency": "NGN",
    "status": "successful",
    "destinationAmount": 2500.000000,
    "customer": {
        "id": 53603,
        "name": "Last Name",
        "email": "test@steph.com",
        "phone": null,
        "createdAt": "2023-07-04 20:11:05",
        "updatedAt": "2023-07-04 20:11:05"
    }
}

Token Generation
Link
here
Encryption Algorithm here