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
accountId*
String
Request Body
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.
{
"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
accountId*
626...44b
populate
users
{
"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
populate
Purchases
limit
10
limit the returned response to a collection of 10 transactions
sort
String
a field to sort the response by
{
"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*
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
amount*
400000
description*
Fund for Airtime
{
"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.
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
accountId*
5d6c3...53d30d
Request Body
blocked*
true
Boolean value to set lock and unlock a sub-account balance
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}}
Last updated