Accounts & Subaccounts

Learn how to create and management sub-accounts

Once you sign up on VeendHQ Business, you automatically have an account created for you.

What is a Sub-account

Each user on VeendHQ can have multiple Sub-accounts for different use cases.

Create a Sub-account

Create a new sub-account.

POST {{BASE_URL}}/v1/accounts/{{ACCOUNT_ID}}/subaccount?accountId={{ID}}

Query Parameters

Request Body

    "status": "success",
    "data": {
        "users": [
        "autoRetry": true,
        "balanceThreshold": 0,
        "accountType": "active",
        "dailyLimit": 0,
        "monthlyLimit": 0,
        "singleTransactionLimit": 0,
        "tags": [],
        "_id": "63a5c3...fb007c",
        "name": "John Doe",
        "webhookURL": "",
        "currency": "NGN",
        "createdAt": "2022-12-23T15:03:38.873Z",
        "__v": 0

Get Sub-account Details

Returns details about a sub-account

GET {{BASE_URL}}/v1/accounts/{{ACCOUNT_ID}}?accountId={{ACCOUNT_ID}}&populate=users

Query Parameters

    "status": "success",
    "data": {
        "users": [
                "twoFactor": false,
                "accounts": [
                "addressBooks": [
                "authentications": [
                "kycVerificationStatus": "not_verified",
                "isBlocked": false,
                "roles": [
                "tags": [],
                "_id": "62603e...204446",
                "firstName": "VeendHQ",
                "lastName": "Inc",
                "businessName": "VeendHQ Inc",
                "referralCode": "YmQbb3xyh3",
                "createdAt": "2022-04-20T16:12:24.745Z",
                "model": "Users",
                "__v": 5,
                "updatedAt": "2022-04-20T16:12:31.046Z",
                "clientId": "15"
        "autoRetry": true,
        "balanceThreshold": 0,
        "tags": [],
        "_id": "626030...20444b",
        "name": "",
        "currency": "NGN",
        "createdAt": "2022-04-20T16:12:24.942Z",
        "__v": 0,
        "balance": 20,
        "savingsId": "15",
        "updatedAt": "2022-04-20T16:12:30.954Z"

Get Account Statements

Get the statement of a sub-account which returns information about all transactions on that sub-account.

Returns sub-account statement

GET {{BASE_URL}}/payments?accountId={{ACCOUNT_ID}}&populate=Purchases&desc=true&limit=5&sort=-_id

Query Parameters

    "status": "success",
    "data": [
            "status": "completed",
            "paymentReference": "31146256165334802640213-",
            "description": "NGN45.5 - USSD Session  - veendhqautolending-1653348004504_2022-05-23T23:20:04.504Z-ussdcharge_PRODS",
            "amount": -45.5,
            "previousBalance": null,
            "newBalance": null,
            "previousUserBalance": 486037.48,
            "newUserBalance": 485991.98,
            "account": "61512e...07ca32",
            "purchase": 163315,
            "paymentProcessor": "VeendHQ",
            "paymentProcessorReference": "449336-withdraw",
            "currency": "NGN",
            "owner": "61512e41ac43b4002907ca32",
            "createdBy": "61512e41ac43b4002907ca32",
            "client": null,
            "developer": null,
            "tags": null,
            "_id": 305907,
            "createdAt": "2022-05-23T23:20:30.000Z",
            "updatedAt": "2022-05-23T23:20:30.000Z",
            "Purchase.purchaseReference": "veendhqautolending-1653348004504_2022-05-23T23:20:04.504Z-ussdcharge_PRODS",
            "Purchase.cost": 45.5,
            "Purchase.merchantFee": 0,
            "Purchase.customerFee": 0,
            "Purchase.cashback": 0,
            "Purchase.referralCommission": 0,
            "Purchase.totalCost": 45.5,
            "Purchase.description": "NGN45.5 - USSD Session  - veendhqautolending-1653348004504_2022-05-23T23:20:04.504Z-ussdcharge_PRODS",
            "Purchase.currency": "NGN",
            "Purchase.status": "completed",
            "Purchase.paid": 1,
            "Purchase.delivered": 0,
            "Purchase.settled": 1,
            "Purchase.canRefund": 0,
            "Purchase.product": "614f38...a51fad",
            "Purchase.productsDetails": {
                "owner": "61512e...07ca32",
                "amount": 45.5,
                "createdBy": "61512e...07ca32",
                "noOverdraft": true,
                "purchaseReference": "veendhqautolending-1653348004504_2022-05-23T23:20:04.504Z-ussdcharge_PRODS"
            "Purchase.ipAddress": "",
            "Purchase.account": "61512e...07ca32",
            "Purchase.deliveryLog": {
                "error": "service provider currently not supported",
                "retryReference": "retry0-305907",
                "paymentReference": 305907
            "Purchase.settlementLog": {},
            "Purchase.refundLog": null,
            "Purchase.validationDetails": null,
            "Purchase.batch": null,
            "Purchase.payment": 305907,
            "Purchase.feeCalculationData": {
                "__v": 0,
                "_id": "614f38...a51fad",
                "fee": 0,
                "code": "USSD",
                "name": "USSD Session ",
                "tags": [
                "type": "oneTime",
                "model": "Products",
                "owner": "61262e...ac1a7c",
                "amount": 0,
                "isSync": false,
                "status": "default",
                "account": "614f38...4e5bf3",
                "enabled": true,
                "feeType": "percentage",
                "cashback": 0,
                "currency": "NGN",
                "featured": false,
                "runCount": 0,
                "canRefund": false,
                "createdAt": "2021-09-25T14:57:22.057Z",
                "createdBy": "61262e...ac1a7c",
                "updatedAt": "2021-09-25T14:57:22.063Z",
                "cashbackType": "percentage",
                "disableRetry": false,
                "providerName": "VeendHQ",
                "additionalFee": 0,
                "hasValidation": false,
                "hasVariations": false,
                "convinienceFee": 0,
                "recurringCount": 0,
                "customerBearsFee": false,
                "hasSubVariations": false,
                "recurringInterval": "none",
                "convinienceFeeType": "percentage",
                "referralCommission": 0,
                "recurringIntervalCount": 1,
                "referralCommissionType": "percentage"
            "Purchase.retryCount": 0,
            "Purchase.owner": "61512e...07ca32",
            "Purchase.createdBy": "61512e...07ca32",
            "Purchase.client": null,
            "Purchase.developer": null,
            "Purchase.tags": null,
            "Purchase._id": 163315,
            "Purchase.createdAt": "2022-05-23T23:20:26.000Z",
            "Purchase.updatedAt": "2022-05-23T23:20:31.000Z"
    "limit": 5,
    "total": 307387,
    "lastId": 299796,
    "totalResult": 20361,
    "isLastPage": false,
    "cached": true

Update sub account detail

Update details of a sub-account

PATCH {{BASE_URL}}/v1/accounts/{{ACCOUNT_ID}}?accountId={{ACCOUNT_ID}}

Request Body

Transfer funds between Sub-accounts

You can send fund from one sub-account to another on VeendHQ Business Account.

Transfer fund to a subaccount

POST {{BASE_URL}}/v1/accounts/{{SENDER_ACCOUNT_ID}}/transfer/{{RECEIVER_ACCOUNT_ID}}?accountId={{ID}}

Request Body

    "status": "success",
    "data": {
        "amount": 400000,

Lock and Unlock Sub-account Balance

A sub-account balance can be locked or unlocked. Locking a sub-account will prevent disbursement of funds from that sub-account.


The BALANCE_ID can be gotten from the response to a GET call for a sub-account detail.

Lock and Unlock SubAccount Balance


Set blocked on the body of the request to true to lock the subaccount balance, otherwise set to false to unblock the account balance.

Query Parameters

Request Body

Get Balance

Get balance for an account or a sub-account.

Return Balance for Account or Sub-Account


Last updated