# Collection Account

### Collection Account (Static Virtual Account)

A **Collection Account** (also called a **Static Virtual Account**) is a persistent virtual account that can be assigned to a merchant/customer for recurring collections. Unlike **Dynamic Virtual Accounts** (generated per transaction), a **Static Account** remains the same and can be reused.

#### Create Collection Account (Static Virtual Account)

This API allows you to create a **Static Virtual Account** (Collection Account) for a merchant/customer. The account can be used to receive bank transfers repeatedly.

**Request Endpoint**

`POST /api/v1/accounts/static`

***

#### Headers

| Header          | Value              |
| --------------- | ------------------ |
| `Authorization` | `Bearer {token}`   |
| `Content-Type`  | `application/json` |
| `accept`        | `*/*`              |

> Ensure you pass the **bearer token retrieved from the authentication login endpoint** as the `Authorization` header.

***

#### Request Body

```json
{
  "accountName": "Testing Account",
  "bvn": "22345678901",
  "email": "testing.account@gmail.com",
  "merchantId": "MRC_0000002451",
  "merchantCode": "Nai0000319",
  "notificationUrl": "https://api.yourcompany.com/webhooks/virtual-account/notification",
  "phoneNumber": "+2348031234567",
  "channel": "API"
}
```

**Request Parameters**

| Field             | Type     | Required | Description                                               |
| ----------------- | -------- | -------- | --------------------------------------------------------- |
| `accountName`     | `string` | Yes      | Name to be tied to the collection account.                |
| `bvn`             | `string` | Yes      | BVN of the account owner/customer.                        |
| `email`           | `string` | Yes      | Email address linked to the account.                      |
| `merchantId`      | `string` | Yes      | Internal merchant identifier (e.g. `MRC_...`).            |
| `merchantCode`    | `string` | Yes      | Merchant code/client code (e.g. `Nai...`).                |
| `notificationUrl` | `string` | Yes      | Webhook URL to receive account/transaction notifications. |
| `phoneNumber`     | `string` | Yes      | Phone number of the customer/merchant contact.            |
| `channel`         | `string` | Yes      | Channel initiating the request (e.g. `API`).              |

***

#### cURL Example

```bash
curl -X 'POST' \
  '{{base-url}}/api/v1/accounts/static' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "accountName": "Testing Account",
  "bvn": "22345678901",
  "email": "testing.account@gmail.com",
  "merchantId": "MRC_0000002451",
  "merchantCode": "Nai0000319",
  "notificationUrl": "https://api.yourcompany.com/webhooks/virtual-account/notification",
  "phoneNumber": "+2348031234567",
  "channel": "API"
}'
```

***

#### Response Codes

| Code  | Meaning     |
| ----- | ----------- |
| `200` | Success     |
| `400` | Bad Request |

***

#### Response Body Example

```json
{
  "data": {
    "id": 171,
    "bankCode": "035",
    "accountNumber": "9961043198",
    "accountName": "Testing Account",
    "bvn": "22345678901",
    "email": "testing.account@gmail.com",
    "accountBalance": 0,
    "merchantId": "MRC_0000002451",
    "merchantCode": "Nai0000319",
    "notificationUrl": "https://api.yourcompany.com/webhooks/virtual-account/notification",
    "isDefault": false,
    "isActive": true,
    "currencyCode": "NGN",
    "phoneNumber": "+2348031234567",
    "channel": "API",
    "createdAt": "2026-01-26T16:41:22.878706+01:00",
    "updatedAt": "2026-01-26T16:41:22.902094+01:00"
  },
  "message": "Static account created successfully",
  "isSuccessful": true
}
```

***

#### Response Parameters

| Field                  | Type      | Description                                                           |
| ---------------------- | --------- | --------------------------------------------------------------------- |
| `isSuccessful`         | `boolean` | Indicates if the request was successful.                              |
| `message`              | `string`  | Human-readable response message.                                      |
| `data.id`              | `number`  | Internal ID for the created collection account.                       |
| `data.bankCode`        | `string`  | Bank code assigned to the virtual account (e.g. `035`).               |
| `data.accountNumber`   | `string`  | The generated static virtual account number.                          |
| `data.accountName`     | `string`  | The account name tied to the static account.                          |
| `data.bvn`             | `string`  | BVN provided during creation.                                         |
| `data.email`           | `string`  | Email provided during creation.                                       |
| `data.accountBalance`  | `number`  | Current balance tracked for the account (if applicable).              |
| `data.merchantId`      | `string`  | Merchant identifier tied to the account.                              |
| `data.merchantCode`    | `string`  | Merchant code tied to the account.                                    |
| `data.notificationUrl` | `string`  | Webhook URL tied to notifications.                                    |
| `data.isDefault`       | `boolean` | Indicates if this is the default collection account for the merchant. |
| `data.isActive`        | `boolean` | Indicates if the account is active.                                   |
| `data.currencyCode`    | `string`  | Currency for the account (e.g. `NGN`).                                |
| `data.phoneNumber`     | `string`  | Phone number provided during creation.                                |
| `data.channel`         | `string`  | Channel used to create the account (e.g. `API`).                      |
| `data.createdAt`       | `string`  | Timestamp when the account was created.                               |
| `data.updatedAt`       | `string`  | Timestamp when the account was last updated.                          |

***

#### Notes / Usage

* Use the returned `accountNumber` as the **Collection Account** for bank transfers.
* `notificationUrl` should be an endpoint that can receive webhook events for updates/notifications related to the static account.
* `isDefault=false` means this account is not the default for the merchant unless later set.

### Get Collection Account by Account Number

This API allows you to **retrieve a Collection Account (Static Virtual Account)** using the **account number**.

***

#### Request Endpoint

`GET /api/v1/accounts/static/{accountNumber}`

***

#### Headers

| Header          | Value            |
| --------------- | ---------------- |
| `Authorization` | `Bearer {token}` |
| `accept`        | `*/*`            |

> Ensure you pass the **bearer token retrieved from the authentication login endpoint** as the `Authorization` header.

***

#### Path Parameter

| Parameter       | Type     | Required | Description                                                        |
| --------------- | -------- | -------- | ------------------------------------------------------------------ |
| `accountNumber` | `string` | Yes      | The static virtual account number to retrieve (e.g. `9961043198`). |

***

#### cURL Example

```bash
curl -X 'GET' \
  '{{base-url}}/api/v1/accounts/static/9961043198' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {token}'
```

***

#### Response Codes

| Code  | Meaning     |
| ----- | ----------- |
| `200` | Success     |
| `400` | Bad Request |

***

#### Response Body Example

```json
{
  "data": {
    "id": 171,
    "bankCode": "035",
    "accountNumber": "9961043198",
    "accountName": "Testing Account",
    "bvn": "22345678901",
    "email": "testing.account@gmail.com",
    "accountBalance": 0,
    "merchantId": "MRC_0000002451",
    "merchantCode": "Nai0000319",
    "notificationUrl": "https://api.yourcompany.com/webhooks/virtual-account/notification",
    "isDefault": false,
    "isActive": true,
    "currencyCode": "NGN",
    "phoneNumber": "+2348031234567",
    "channel": "API",
    "createdAt": "2026-01-26T16:41:22.878706+01:00",
    "updatedAt": "2026-01-26T16:41:22.902094+01:00"
  },
  "message": "Account retrieved successfully",
  "isSuccessful": true
}
```

***

#### Response Parameters

| Field                  | Type      | Description                                              |
| ---------------------- | --------- | -------------------------------------------------------- |
| `isSuccessful`         | `boolean` | Indicates if the request was successful.                 |
| `message`              | `string`  | Human-readable response message.                         |
| `data.id`              | `number`  | Internal ID of the static account.                       |
| `data.bankCode`        | `string`  | Bank code assigned to the virtual account (e.g. `035`).  |
| `data.accountNumber`   | `string`  | The static virtual account number.                       |
| `data.accountName`     | `string`  | Name tied to the account.                                |
| `data.bvn`             | `string`  | BVN tied to the account.                                 |
| `data.email`           | `string`  | Email tied to the account.                               |
| `data.accountBalance`  | `number`  | Current balance tracked for the account (if applicable). |
| `data.merchantId`      | `string`  | Merchant identifier tied to the account.                 |
| `data.merchantCode`    | `string`  | Merchant code/client code tied to the account.           |
| `data.notificationUrl` | `string`  | Webhook URL for notifications.                           |
| `data.isDefault`       | `boolean` | Indicates if the account is set as default.              |
| `data.isActive`        | `boolean` | Indicates if the account is active.                      |
| `data.currencyCode`    | `string`  | Currency (e.g. `NGN`).                                   |
| `data.phoneNumber`     | `string`  | Phone number tied to the account.                        |
| `data.channel`         | `string`  | Channel used to create the account (e.g. `API`).         |
| `data.createdAt`       | `string`  | Timestamp when the account was created.                  |
| `data.updatedAt`       | `string`  | Timestamp when the account was last updated.             |