> For the complete documentation index, see [llms.txt](https://docs.advancly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.advancly.com/virtual-and-dynamic-account.md).

# Virtual & Dynamic Account

## Create Individual Account

<mark style="color:green;">`POST`</mark> `{{`<mark style="color:red;">`baseUrl`</mark>`}}/api/v2/client/wallet/individual/create`

<details>

<summary>Headers</summary>

<table><thead><tr><th width="226.5234375">Key</th><th width="117.24609375">Value</th><th>Description</th></tr></thead><tbody><tr><td>X-Virtual-Account-Type</td><td>Static/Collection</td><td>Indicate whether it's Static or Collection, if you have more than 1 account type configuration.</td></tr></tbody></table>

</details>

<details>

<summary>Sample Request &#x26; Fields Details</summary>

```json
{
    "first_name": "Emeka",
    "last_name": "Okoro",
    "dob": "1979-08-12",
    "address": "75464 Lowell Lane",
    "gender": "Male", // Female
    "phone": "0911831****",
    "email": "emek*****@yopmail.com",
    "bvn": "280303*****"
}
```

<table><thead><tr><th width="226.5234375">Name</th><th width="117.24609375">Type</th><th>Description</th></tr></thead><tbody><tr><td>first_name</td><td>string</td><td>First name of the customer's account</td></tr><tr><td>last_name</td><td>string</td><td>Last name of the customer's account</td></tr><tr><td>dob</td><td>Date</td><td>Date of birth formatted in (yyyy-dd-mm)</td></tr><tr><td>address</td><td>string</td><td>Address of the customer's account</td></tr><tr><td>gender</td><td>number</td><td>Customer's gender (Male or Female)</td></tr><tr><td>phone</td><td>string</td><td>Customer's phone no</td></tr><tr><td>email</td><td>string</td><td>Customer's email address</td></tr><tr><td>bvn</td><td>string</td><td>Customer's valid BVN</td></tr></tbody></table>

</details>

<details>

<summary>Response</summary>

Ok (200)

```json
{
    "message": "Account created successfully",
    "status": true,
    "status_code": 200,
    "data": {
        "account_name": "Paelyt - Emeka Okoro",
        "account_number": "001261****"
    }
}
```

Bad Request (409)

```json
{
    "message": "An account already exists for this customer.",
    "status": false,
    "status_code": 409
}
```

</details>

## Create Corporate Account

<mark style="color:green;">`POST`</mark> `{{`<mark style="color:red;">`baseUrl`</mark>`}}/api/v2/client/wallet/corporate/create`

<details>

<summary>Headers</summary>

<table><thead><tr><th width="226.5234375">Key</th><th width="117.24609375">Value</th><th>Description</th></tr></thead><tbody><tr><td>X-Virtual-Account-Type</td><td>Static/Collection</td><td>Indicate whether it's Static or Collection, if you have more than 1 account type configuration.</td></tr></tbody></table>

</details>

<details>

<summary>Sample Request &#x26; Fields Details</summary>

```json
{
    "rc_number": "7445**",
    "businessTypeEnum":5,
    "business_name": "Schoen, Beier and Predovic",
    "incorporation_date": "1979-08-12",
    "address": "7199 Emilio Islands",
    "phone": "0911831****",
    "email": "emek*****@yopmail.com",
    "bvn": "280303*****"
}
```

<table><thead><tr><th width="226.5234375">Name</th><th width="117.24609375">Type</th><th>Description</th></tr></thead><tbody><tr><td>rc_number</td><td>string</td><td>Business registration number (CAC)</td></tr><tr><td>business_name</td><td>string</td><td>Business registered name</td></tr><tr><td>incorporation_date</td><td>string</td><td>Business date of incorporation</td></tr><tr><td>address</td><td>string</td><td>Address of the customer's account</td></tr><tr><td>phone</td><td>number</td><td>Customer's phone no</td></tr><tr><td>email</td><td>string</td><td>Customer's email address</td></tr><tr><td>bvn</td><td>string</td><td>Customer's valid BVN</td></tr></tbody></table>

</details>

<details>

<summary>Response</summary>

Ok (200)

```json
{
    "message": "Account created successfully",
    "status": true,
    "status_code": 200,
    "data": {
        "account_name": "Paelyt - Emeka Okoro",
        "account_number": "001261****"
    }
}
```

Bad Request (409)

```json
{
    "message": "An account already exists for this customer.",
    "status": false,
    "status_code": 400
}
```

</details>

## Generate Dynamic Account

<mark style="color:green;">`POST`</mark> `{{`<mark style="color:red;">`baseUrl`</mark>`}}/api/v2/client/wallet/dynamic/generate`

<details>

<summary>Sample Request &#x26; Fields Details</summary>

```json
{
    "account_name": "Adrace",
    "transaction_ref": "Advancly-1827hdbdhb7273881bdbj",
    "transaction_amount": 11000,
    "duration": 30
}
```

<table><thead><tr><th width="226.5234375">Name</th><th width="117.24609375">Type</th><th>Description</th></tr></thead><tbody><tr><td>account_name</td><td>string *</td><td>The account of the dynamic account</td></tr><tr><td>transaction_ref</td><td>string*</td><td>The unique ref number of the transaction</td></tr><tr><td>transaction_amount</td><td>number</td><td>The transaction amount that being expected into the account.<br>This is optional</td></tr><tr><td>duration</td><td>number *</td><td>The duration for which the account will be valid for (Min 15min) and (Max 30min)</td></tr></tbody></table>

</details>

<details>

<summary>Response</summary>

Ok (200)

```json
{
    "data": {
        "account_name": "Waakae - Sosanya",
        "account_number": "0041301167",
        "duration": 15,
        "expiry_datetime": "2026-03-30T08:25:44.204664Z"
    },
    "message": "Dynamic account generated successfully.",
    "status": true,
    "status_code": 201
}
```

Bad Request (409)

```json
{
    "message": "Duration should be between 15 - 30 min before expiry.",
    "status": false,
    "status_code": 400
}
```

</details>

## Account Details

<mark style="color:blue;">`GET`</mark> `{{`<mark style="color:red;">`baseUrl`</mark>`}}/api/v2/client/wallet?account_number=001261****`

| Name            | Type   | Description            |
| --------------- | ------ | ---------------------- |
| account\_number | string | virtual account number |

<details>

<summary>Response</summary>

Ok (200)

```json
{
    "data": [
        {
            "accountName": "Paelyt - Emeka Okoro",
            "accountNumber": "001261****",
            "globalAccountNumber": "9038299384-5",
            "accountBalance": 7895876.53,
            "availableBalance": 7895876.53
        }
    ],
    "message": "Success",
    "status": true,
    "status_code": 200
}
```

Bad Request (400)

```json
{
    "message": "Invalid account, kindly check account number.",
    "status": false,
    "status_code": 400
}
```

</details>

## Financial Institutions

<mark style="color:blue;">`GET`</mark> `{{`<mark style="color:red;">`baseUrl`</mark>`}}/api/v2/client/wallet/financial_institutions`

<details>

<summary>Response</summary>

```json
{
    "message": "Success",
    "status": true,
    "status_code": 200,
    "data": [
        {
            "bank_code": "999461",
            "bank_name": "Advancly MFB",
            "png_logo_url": null,
            "svg_logo_url": null
        },
        {
            "bank_code": "120001",
            "bank_name": "9 payment service Bank",
            "png_logo_url": null,
            "svg_logo_url": null
        },
        {
            "bank_code": "090270",
            "bank_name": "AB MICROFINANCE BANK",
            "png_logo_url": null,
            "svg_logo_url": null
        },
        {
            "bank_code": "070010",
            "bank_name": "ABBEY MORTGAGE BANK",
            "png_logo_url": "",
            "svg_logo_url": ""
        },
        {
            "bank_code": "090260",
            "bank_name": "ABOVE ONLY MICROFINANCE BANK",
            "png_logo_url": "",
            "svg_logo_url": ""
        },
        {
            "bank_code": "090197",
            "bank_name": "ABU MICROFINANCE BANK",
            "png_logo_url": null,
            "svg_logo_url": null
        }
    ]
}
```

</details>

## Name Enquiry

<mark style="color:blue;">`GET`</mark>` ``{{`<mark style="color:red;">`baseUrl`</mark>`}}/api/v2/client/wallet/name_enquiry?account_number=9038299384&bank_code=000481`

#### Query Parameters

| Name            | Type   | Description         |
| --------------- | ------ | ------------------- |
| account\_number | string | bank account number |
| bank\_code      | string | nibss bank code     |

<details>

<summary>Response</summary>

```json
{
    "data": {
        "account_number": "9038299384",
        "account_name": "OLUWADAMILOLA OGUNLUSI",
        "kyc_tier": "3"
    },
    "message": "Success",
    "status": true,
    "status_code": 200
}
```

</details>

## Transfer

<mark style="color:green;">`POST`</mark> `{{`<mark style="color:red;">`baseUrl`</mark>`}}/api/v2/client/wallet/transfer`

<details>

<summary>Sample Request &#x26; Fields Details</summary>

```json
{
    "sender_account_number": "9038299384",
    "recipient_account_number": "7037662603",
    "recipient_account_name": "PAUL IKHIDE",
    "recipient_bank_code": "999461",
    "amount": 1200,
    "narration": "Glorious test battle",
    "reference": "Advancly-HAUUSIKSNJWUWJSN61728829289"
}
```

<table><thead><tr><th width="226.5234375">Name</th><th width="117.24609375">Type</th><th>Description</th></tr></thead><tbody><tr><td>sender_account_number</td><td>string</td><td>account number of the transfer initiator</td></tr><tr><td>recipient_account_number</td><td>string</td><td>account number of the transfer recipient</td></tr><tr><td>recipient_account_name</td><td>string</td><td>bank account name retrieved from a name inquiry</td></tr><tr><td>recipient_bank_code</td><td>string</td><td>NIBSS bank code of the receiving bank</td></tr><tr><td>amount</td><td>number</td><td>transfer amount</td></tr><tr><td>narration</td><td>string</td><td>transfer narration</td></tr><tr><td>reference</td><td>string</td><td>transaction reference, e.g., (Advancly-J178IND172891JAHSEE)</td></tr></tbody></table>

</details>

<details>

<summary>Response</summary>

Ok (200)

```json
{
    "response_code": "00",
    "message": "Successful",
    "status": true,
    "status_code": 200,
    "data": {
        "currency": "NGN",
        "sender_account_name": "OLUWADAMILOLA OGUNLUSI",
        "sender_account_number": "9038299384",
        "sender_bank_code": "999461",
        "sender_bank_name": "Advancly MFB",
        "recipient_account_name": "PAUL IKHIDE",
        "recipient_account_number": "7037662603",
        "recipient_bank_code": "999461",
        "recipient_bank_name": "Advancly MFB",
        "transaction_id": "0",
        "transaction_reference": "Advancly-HAUUSIKSNJWUWJSN61728829289",
        "session_id": null,
        "narration": "Glorious test battle",
        "transaction_status": "Completed",
        "amount": 1200,
        "transaction_charge": 0,
        "transaction_message": "Success",
        "transaction_date": "2025-03-29T23:12:41.646117+01:00"
    }
}
```

Bad Request (400)

```json
{
    "response_code": "99",
    "message": "Transfer limit exceeded the configured limit of 1000000.",
    "status": false,
    "status_code": 400
}
```

```json
{
    "response_code": "A102",
    "message": "Duplicate Reference",
    "status": false,
    "status_code": 400
}
```

</details>

## TSQ

<mark style="color:blue;">`GET`</mark> `{{`<mark style="color:red;">`baseUrl`</mark>`}}/api/v2/client/wallet/transaction/{transactionReference}`

<details>

<summary>Response</summary>

Ok (200)

```json
{
    "data": {
        "id": 6,
        "externalReferenceNumber": "Advancly-HAUUSIKSNJWUWJSN617288292814",
        "sessionId": null,
        "senderAccountName": "OLUWADAMILOLA OGUNLUSI",
        "senderAccountNumber": "9038299384",
        "senderBankCode": "999461",
        "senderBankName": "Advancly MFB",
        "recipientAccountName": "PAUL IKHIDE",
        "recipientAccountNumber": "7037662603",
        "recipientBankCode": "999461",
        "recipientBankName": "Advancly MFB",
        "amount": 1200.00,
        "feeCharge": 0.00,
        "narration": "Glorious test battle/Advancly-HAUUSIKSNJWUWJSN617288292814",
        "transactionStatus": "Completed", // Completed, Failed, Processing
        "transactionType": "Outward",
        "responseCode": "00",
        "responseMessage": "Success",
        "channelCode": 9,
        "transactionDate": "2025-04-09T14:59:08.992077",
        "createdDateTime": "2025-04-09T14:59:15.162074"
    },
    "message": "Success",
    "status": true,
    "status_code": 200
}
```

Bad Request (404)

```json
{
    "message": "Record not found",
    "status": false,
    "status_code": 404
}
```

</details>

## Transactions

<mark style="color:blue;">`GET`</mark>` ``{{`<mark style="color:red;">`baseUrl`</mark>`}}/api/v2/client/wallet/transactions?account_number=9038299384&start_date=2025-03-15&end_date=2025-03-21&page=1&page_size=10`

#### Query Parameters

| Name            | Type              | Description                   |
| --------------- | ----------------- | ----------------------------- |
| account\_number | string            | account no                    |
| start\_date     | date (yyyy-mm-dd) | start date of the transaction |
| end\_date       | date (yyyy-mm-dd) | end date of the transaction   |
| page            | number            | page number (default 1)       |
| page\_size      | number            | page size number (default 10) |

<details>

<summary>Response</summary>

Ok (200)

```json
{
    "page": 1,
    "pageSize": 10,
    "totalCount": 31,
    "totalPages": 4,
    "message": "Success",
    "status": true,
    "status_code": 200,
    "data": [
        {
            "accountNumber": "9038299384",
            "transactionAmount": 980.000000,
            "balance": 8972888.531765,
            "transactionDate": "2025-03-19T00:00:00",
            "createdDate": "2025-03-19T08:12:33.956629",
            "transactionType": "DEBIT",
            "narration": "Glorious test battle",
            "clientId": 31,
            "currencyCode": "NGN",
            "senderDetails": {
                "name": "OLUWADAMILOLA OGUNLUSI",
                "bankName": "Advancly MFB",
                "accountNumber": "9038299384"
            },
            "receiverDetails": {
                "name": "PAUL IKHIDE",
                "bankName": "Advancly MFB",
                "accountNumber": "7037662603"
            },
            "sessionId": null
        },
        {
            "accountNumber": "9038299384",
            "transactionAmount": 1200.000000,
            "balance": 8971688.531765,
            "transactionDate": "2025-03-19T00:00:00",
            "createdDate": "2025-03-19T08:14:28.131603",
            "transactionType": "DEBIT",
            "narration": "Glorious test battle",
            "clientId": 31,
            "currencyCode": "NGN",
            "senderDetails": {
                "name": "OLUWADAMILOLA OGUNLUSI",
                "bankName": "Advancly MFB",
                "accountNumber": "9038299384"
            },
            "receiverDetails": {
                "name": "PAUL IKHIDE",
                "bankName": "Advancly MFB",
                "accountNumber": "7037662603"
            },
            "sessionId": null
        },
        {
            "accountNumber": "9038299384",
            "transactionAmount": 580.000000,
            "balance": 8971108.531765,
            "transactionDate": "2025-03-19T00:00:00",
            "createdDate": "2025-03-19T08:17:50.657354",
            "transactionType": "DEBIT",
            "narration": "Glorious test battle",
            "clientId": 31,
            "currencyCode": "NGN",
            "senderDetails": {
                "name": "OLUWADAMILOLA OGUNLUSI",
                "bankName": "Advancly MFB",
                "accountNumber": "9038299384"
            },
            "receiverDetails": {
                "name": "PAUL IKHIDE",
                "bankName": "Advancly MFB",
                "accountNumber": "7037662603"
            },
            "sessionId": null
        }
    ]
}
```

</details>

## Block virtual account

<mark style="color:green;">`POST`</mark> `{{`<mark style="color:red;">`baseUrl`</mark>`}}/api/v2/client/wallet/block_account`

<details>

<summary>Sample Request &#x26; Field Details</summary>

```json
{
    "accountNumber": "0064813141",
    "reason": "fraud"
}
```

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| accountNumber | string | account number to be blocked           |
| reason        | string | reason for blocking the account number |

</details>

<details>

<summary>Response</summary>

Ok (200)

```json
{
    "message": " Account Blocked Successfully",
    "status": true,
    "status_code": 200
}
```

</details>

## Unblock virtual account

<mark style="color:green;">`POST`</mark> `{{`<mark style="color:red;">`baseUrl`</mark>`}}/api/v2/client/wallet/unblock_account`

<details>

<summary>Sample Request &#x26; Field Details</summary>

```json
{
    "accountNumber": "0064813141",
    "reason": "resolved"
}
```

| Name          | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| accountNumber | string | account number to be blocked             |
| reason        | string | reason for unblocking the account number |

</details>

<details>

<summary>Response</summary>

Ok (200)

```json
{
    "message": " Account UnBlocked Successfully",
    "status": true,
    "status_code": 200
}
```

</details>

***

<details>

<summary><strong>Transaction Response Codes</strong></summary>

<table><thead><tr><th width="98.11328125">Code</th><th width="394.1328125">Description</th><th>Category</th></tr></thead><tbody><tr><td>00</td><td>Approved or Completed Successfully</td><td>Successful</td></tr><tr><td>06</td><td>Dormant Account</td><td>Failed</td></tr><tr><td>07</td><td>Invalid Account</td><td>Failed</td></tr><tr><td>13</td><td>Invalid Amount</td><td>Failed</td></tr><tr><td>26</td><td>Duplicate Record</td><td>Failed</td></tr><tr><td>51</td><td>Insufficient Funds</td><td>Failed</td></tr><tr><td>61</td><td>Transfer Limit Exceeded</td><td>Failed</td></tr><tr><td>99</td><td>Transaction Failed</td><td>Failed</td></tr><tr><td>A100</td><td>Transfer to The Same Account</td><td>Failed</td></tr><tr><td>A101</td><td>Insufficient Bbalance</td><td>Failed</td></tr><tr><td>A102</td><td>Duplicate Reference</td><td>Failed</td></tr><tr><td>A500</td><td>Internal Server Error</td><td>Failed</td></tr></tbody></table>

</details>

<details>

<summary><strong>Interbank Test Accounts (Dev)</strong></summary>

<table><thead><tr><th>Bank Code</th><th>Account No</th><th>Account Name</th><th width="111.75">KYC Level</th><th>BVN</th></tr></thead><tbody><tr><td>000014</td><td>9986840979</td><td>Waller Livingston</td><td>1</td><td>537595960283</td></tr><tr><td>000014</td><td>1471023622</td><td>Moon Sanchez</td><td>3</td><td>660477154602</td></tr><tr><td>000016</td><td>3811637086</td><td>Earline Mills</td><td>3</td><td>853119474502</td></tr><tr><td>000014</td><td>2359862016</td><td>Hart Snider</td><td>3</td><td>547014819401</td></tr><tr><td>000016</td><td>9914872061</td><td>Durham Reese</td><td>2</td><td>908631517477</td></tr><tr><td>000001</td><td>1091016606</td><td>Kari Sargent</td><td>3</td><td>115427203295</td></tr><tr><td>000014</td><td>9389590545</td><td>Ola Murphy</td><td>3</td><td>312583939236</td></tr><tr><td>000015</td><td>1830956253</td><td>Rojas Adams</td><td>3</td><td>429149041264</td></tr><tr><td>000015</td><td>5942277535</td><td>Melva Mueller</td><td>1</td><td>950918423663</td></tr><tr><td>000013</td><td>9728072421</td><td>Felecia Lester</td><td>1</td><td>506874908045</td></tr></tbody></table>

</details>