# Accounts & Subaccounts

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.

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/v1/accounts/{{ACCOUNT_ID}}/subaccount?accountId={{ID}}`

#### Query Parameters

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| accountId<mark style="color:red;">\*</mark> | String |             |

#### Request Body

| Name                                       | Type         | Description                                                                           |
| ------------------------------------------ | ------------ | ------------------------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark>     | John Doe     | A name for the sub account                                                            |
| user<mark style="color:red;">\*</mark>     | 62bff....e6f | userId returned from the sign up or login.                                            |
| webhookurl                                 | String       | A webhook url endpoint to be triggered when certain event occur                       |
| currency<mark style="color:red;">\*</mark> | NGN          | The currency to be used for the sub account. This should be same as the main account. |

{% tabs %}
{% tab title="200: OK Sample success response for created sub-account" %}
{% code overflow="wrap" %}

```json
{
    "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
    }
}

```

{% endcode %}
{% endtab %}
{% endtabs %}

### Get Sub-account Details

## Returns details about a sub-account

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/v1/accounts/{{ACCOUNT_ID}}?accountId={{ACCOUNT_ID}}&populate=users`

#### Query Parameters

| Name                                        | Type      | Description |
| ------------------------------------------- | --------- | ----------- |
| accountId<mark style="color:red;">\*</mark> | 626...44b |             |
| populate                                    | users     |             |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "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": "test@email.com",
        "currency": "NGN",
        "createdAt": "2022-04-20T16:12:24.942Z",
        "__v": 0,
        "balance": 20,
        "savingsId": "15",
        "updatedAt": "2022-04-20T16:12:30.954Z"
    }
}
```

{% endtab %}
{% endtabs %}

### Get Account Statements

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

## Returns sub-account statement

<mark style="color:blue;">`GET`</mark> `{{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                                |

{% tabs %}
{% tab title="200: OK Sample success response limited to 1 statement" %}

```javascript
{
    "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
}
```

{% endtab %}
{% endtabs %}

### Update sub account detail

## Update details of a sub-account

<mark style="color:purple;">`PATCH`</mark> `{{BASE_URL}}/v1/accounts/{{ACCOUNT_ID}}?accountId={{ACCOUNT_ID}}`

#### Request Body

| Name                                   | Type      | Description |
| -------------------------------------- | --------- | ----------- |
| name<mark style="color:red;">\*</mark> | 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

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/v1/accounts/{{SENDER_ACCOUNT_ID}}/transfer/{{RECEIVER_ACCOUNT_ID}}?accountId={{ID}}`

#### Request Body

| Name                                          | Type             | Description |
| --------------------------------------------- | ---------------- | ----------- |
| amount<mark style="color:red;">\*</mark>      | 400000           |             |
| description<mark style="color:red;">\*</mark> | Fund for Airtime |             |

{% tabs %}
{% tab title="200: OK Sample success response" %}
{% code overflow="wrap" %}

```json

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

{% endcode %}
{% endtab %}
{% endtabs %}

### 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.

{% hint style="info" %}
**BALANCE\_ID**

The **BALANCE\_ID** can be gotten from the response to a **GET** call for a sub-account detail.
{% endhint %}

## Lock and Unlock SubAccount Balance

<mark style="color:purple;">`PATCH`</mark> `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 balanc&#x65;**,** otherwise set to **false** to unblock the account balance.

#### Query Parameters

| Name                                        | Type           | Description |
| ------------------------------------------- | -------------- | ----------- |
| accountId<mark style="color:red;">\*</mark> | 5d6c3...53d30d |             |

#### Request Body

| Name                                      | Type | Description                                                |
| ----------------------------------------- | ---- | ---------------------------------------------------------- |
| blocked<mark style="color:red;">\*</mark> | true | Boolean value to set lock and unlock a sub-account balance |

{% tabs %}
{% tab title="200: OK " %}

```json
```

{% endtab %}
{% endtabs %}

### Get Balance

Get balance for an account or a sub-account.

## Return Balance for Account or Sub-Account

<mark style="color:blue;">`GET`</mark> `https://test.veendhq.com/v1/balances/?account={{ACCOUNT_ID}}&accountId={{ACCOUNT_ID}}`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veendhq.com/accounts-and-subaccounts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.