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

Name	Type	Description
accountId*	String

Request Body

Name	Type	Description
name*	John Doe	A name for the sub account
user*	62bff....e6f	userId returned from the sign up or login.
webhookurl	String	A webhook url endpoint to be triggered when certain event occur
currency*	NGN	The currency to be used for the sub account. This should be same as the main account.

200: OK Sample success response for created sub-account

{
    "status": "success",
    "data": {
        "users": [
            "6342d9...306aa9"
        ],
        "autoRetry": true,
        "balanceThreshold": 0,
        "accountType": "active",
        "dailyLimit": 0,
        "monthlyLimit": 0,
        "singleTransactionLimit": 0,
        "tags": [],
        "_id": "63a5c3...fb007c",
        "name": "John Doe",
        "webhookURL": "https://eoqyr90lznnx93w.m.pipedream.net",
        "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

Name	Type	Description
accountId*	626...44b
populate	users

200: OK

{
    "status": "success",
    "data": {
        "users": [
            {
                "twoFactor": false,
                "accounts": [
                    "626030...20444b"
                ],
                "addressBooks": [
                    "626030...204448"
                ],
                "authentications": [
                    "626030e...20444f"
                ],
                "kycVerificationStatus": "not_verified",
                "isBlocked": false,
                "roles": [
                    "626030...204455",
                    "623b45...d29738"
                ],
                "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": "[email protected]",
        "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

Name	Type	Description
populate	Purchases
limit	10	limit the returned response to a collection of 10 transactions
sort	String	a field to sort the response by

200: OK Sample success response limited to 1 statement

{
    "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": "34.243.15.4",
            "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": [
                    "percentage",
                    "percentage",
                    "percentage",
                    "percentage",
                    "USSD",
                    "USSD",
                    "Session",
                    "",
                    "VeendHQ",
                    "614f38...4e5bf3",
                    "61262e...ac1a7c",
                    "61262e...ac1a7c",
                    "NGN"
                ],
                "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

Name	Type	Description
name*	Peter Pan

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

Name	Type	Description
amount*	400000
description*	Fund for Airtime

200: OK Sample success response

{
    "status": "success",
    "data": {
        "status":"completed",
        "amount": 400000,
        "paymentReference":"31885182152587292618013"
    }
}

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.

BALANCE_ID

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

Lock and Unlock SubAccount Balance

PATCH https://test.veendhq.com/v1/balances/{{BALANCE_ID}}?accountId={{ACCOUNT_ID}}

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

Name	Type	Description
accountId*	5d6c3...53d30d

Request Body

Name	Type	Description
blocked*	true	Boolean value to set lock and unlock a sub-account balance

200: OK

Get Balance

Get balance for an account or a sub-account.

Return Balance for Account or Sub-Account

GET https://test.veendhq.com/v1/balances/?account={{ACCOUNT_ID}}&accountId={{ACCOUNT_ID}}