Account

Account Folder

This folder contains endpoints related to managing accounts. It includes functionality for creating accounts, fetching account details, updating account information, and performing other operations related to customer accounts. Below are the key endpoints available in this folder:

1. Create Account

   • Endpoint: POST /v1/accounts
   • Description: This endpoint is used to create a new account for a customer.
   • Request Body:
     • bvn (string): The customer's BVN (Bank Verification Number).
     • first_name (string): The first name of the customer.
     • last_name (string): The last name of the customer.
     • date_of_birth (string): The customer's date of birth (in the format DD-MM-YYYY).
     • phone_number (string): The customer's phone number.
     • email (string): The customer's email address.
     • address (string): The customer's physical address.
   • Response:
     • Returns a success message with the account details.

2. Fetch Static Account Details

   • Endpoint: GET /v1/accounts/static/:account_number
   • Description: This endpoint fetches the account details for a specific customer.
   • Path Parameters:
     • account_number (string): The account number of the customer whose account details are being fetched.
   • Response:
     • Returns the account details of the specified customer.

3. Fetch Dynamic Account Details

   • Endpoint: GET /v1/accounts/dynamic/:account_number
   • Description: This endpoint fetches the account details for a specific customer.
   • Path Parameters:
     • account_number (string): The account number of the customer whose account details are being fetched.
   • Response:
     • Returns the account details of the specified customer.

4. Close Account

   • Endpoint: DELETE /v1/accounts/:account_number
   • Description: This endpoint is used to delete a customer account.
   • Path Parameters:
     • account_number (string): The account number of the customer whose account is to be deleted.
   • Response:
     • Returns a success message confirming that the account has been deleted.

Error Handling:

• For all endpoints, appropriate HTTP status codes will be returned for different scenarios, such as:
  • 400 Bad Request: Missing or invalid parameters.
  • 404 Not Found: The specified account does not exist.
  • 500 Internal Server Error: A problem occurred on the server.

Notes:

• Ensure that the X-API-Key header is included for authentication: X-API-Key: API_KEY

Create dynamic virtual account

Create Dynamic Account

• Endpoint: POST /v1/accounts/dynamic
• Description:
  This endpoint generates a dynamic virtual account tied to a specific transaction. The account is temporary and will expire after the specified duration. It is primarily used for one-time payments.
• Request Headers:
  • X-API-Key: Your API key for authentication.
• Request Body:
  {
  "amount": 100.00,
  "reference": "yofddearndcdss",
  "duration_in_minutes": 30
  }
• Body Parameters:
  • amount (number, required): The expected amount to be paid into the dynamic account.
  • reference (string, optional): A unique identifier for the transaction. If not provided, one will be auto-generated.
  • duration_in_minutes (integer, required): How long the account should stay active before expiration.
• Response:
  • Returns the dynamic account details including:
    • account_number
    • account_name
    • bank_name
    • expiration_time
    • reference
• Possible Status Codes:
  • 201 Created: Dynamic account successfully generated.
  • 400 Bad Request: Invalid or missing input fields.
  • 409 Conflict: Reference already exists.
  • 500 Internal Server Error: An error occurred during account generation.
• Note:
  • This account is valid for a limited time only.
  • It is recommended to monitor the expiration timestamp to ensure payment is received within the valid window.

Method: POST

{{BASE_URL}}/accounts/dynamic

Headers

Content-Type	Value
X-API-Key	X-API-Key

Body (raw)

{
  "amount": 100.0,
  "reference": "yofddearndcdss",
  "duration_in_minutes": 30
}

🔑 Authentication noauth

Param	value	Type

Response: 201

Response example:

{
  "success": true,
  "message": "Virtual account created successfully",
  "data": {
    "amount": 100,
    "reference": "yofddeuyiarndcdss",
    "expiration_time": "2025-09-26T10:54:11.7017025Z",
    "account_name": "Dynamic Test Account",
    "account_number": "4097553750",
    "bank_name": "FCMB MFB",
    "bank_code": "090409"
  }
}

Create static account

Create Static Account

• Endpoint: POST /v1/accounts/static
• Description:
  This endpoint is used to create a static virtual account for a user. A static account is permanently associated with the user and can be used for receiving payments multiple times.
• Request Headers:
  • X-API-Key: Your API key for authentication.
• Body Parameters:
• email_address (string, required): The email of the user to whom the static account will be linked.
• first_name (string, required): The first name of the user.
• last_name (string, required): The last name of the user.
• phone_number (string, required): The user’s phone number.
• Response:
• Returns the details of the created static account including the account number, account name, and bank name.
• Possible Status Codes:
• 201 Created: Static account successfully created.
• 400 Bad Request: Missing or invalid fields in the request.
• 409 Conflict: Account already exists with the provided email or phone number.
• 500 Internal Server Error: A problem occurred while processing the request.
• Note:
  The static account created can be used by the customer to receive funds repeatedly. It is uniquely tied to the user profile.

Method: POST

{{BASE_URL}}/accounts/static

Headers

Content-Type	Value
X-API-Key	X-API-Key

Body (raw)

{
  "email_address": "gwanja@gmail.com",
  "first_name": "Liman",
  "last_name": "Dauda",
  "phone_number": "08092717412"
}

🔑 Authentication noauth

Param	value	Type

Response: 201

Response example:

{
  "success": true,
  "message": "Virtual account created successfully",
  "data": {
    "account_name": "Jibril Mohammed",
    "account_number": "7582757982",
    "bank_name": "FCMB MFB",
    "bank_code": "090409",
    "currency": "NGN"
  }
}

Get static virtual account details

Get Static Virtual Account Detail

• Endpoint: GET /v1/accounts/static/:account_number
• Description:
  Retrieves the details of a static virtual account using the account number. Useful for verifying the owner or status of a static account.
• Request Headers:
  • X-API-Key: Your API key for authentication.
• Path Parameter:
  • account_number (string, required): The static virtual account number to look up.
• Response:
  • Returns the static account details including:
    • account_number
    • account_name
    • bank_name
    • associated user information (e.g., email, phone number)
• Possible Status Codes:
  • 200 OK: Account details retrieved successfully.
  • 404 Not Found: No static account found with the provided account number.
  • 500 Internal Server Error: An error occurred while fetching the account details.
• Note:
  • This endpoint is read-only and can be used to verify existing virtual accounts by third-party systems or for customer service operations.

Method: GET

{{BASE_URL}}/accounts/static/:account_number

Headers

Content-Type	Value
X-API-Key	X-API-Key

Query Params

Param	value
	null

🔑 Authentication noauth

Param	value	Type

Response: 200

Response example:

{
  "success": true,
  "message": "Virtual account details retrieved successfully",
  "data": {
    "id": "7bf97187-104c-45f6-8245-5dd30fd9529b",
    "merchant_id": "1ed909ea-f561-4166-a8d8-50589e40ecc0",
    "environment": "SANDBOX",
    "currency": "NGN",
    "bank_name": "FCMB MFB",
    "bank_code": "090409",
    "account_name": "Jibril Mohammed",
    "account_number": "7582757982",
    "updated_at": "2025-09-26T10:25:38.53272Z",
    "created_at": "2025-09-26T10:25:38.53272Z",
    "booked_balance": 0,
    "available_balance": 0,
    "status": "ACTIVE",
    "updated": false,
    "user_id": "e4a36dcc-38d9-4973-9457-5db8cc126e0e",
    "account_type": "STATIC",
    "expiry_time": null,
    "account_category": "CUSTOMER",
    "tier": ""
  }
}

Response: 403

Response example:

{
  "success": false,
  "message": "account is closed - no operations can be performed on a closed account"
}

Get dynamic virtual account details

Get Dynamic Virtual Account Detail

• Endpoint: GET /v1/accounts/dynamic/:account_number
• Description:
  Retrieves the details of a dynamic virtual account using the account number. This is useful for validating a temporary account created for one-time payments.
• Request Headers:
  • X-API-Key: Your API key for authentication.
• Path Parameter:
  • account_number (string, required): The dynamic virtual account number to retrieve.
• Response:
  • Returns details of the dynamic account including:
    • account_number
    • account_name
    • bank_name
    • expiration_time
    • reference
    • amount
    • status
• Possible Status Codes:
  • 200 OK: Account details successfully retrieved.
  • 404 Not Found: No dynamic account exists with the provided account number.
  • 410 Gone: Account has expired and is no longer active.
  • 500 Internal Server Error: An unexpected error occurred while retrieving the account details.
• Note:
  • Dynamic accounts are time-bound. If the account has expired, the system may respond with a 410 Gone status.

Method: GET

{{BASE_URL}}/accounts/dynamic/:account_number

Headers

Content-Type	Value
X-API-Key	X-API-Key

Query Params

Param	value
	null

🔑 Authentication noauth

Param	value	Type

Response: 200

Response example:

{
  "success": true,
  "message": "Virtual account details retrieved successfully",
  "data": {
    "id": "fbe211ec-90e1-4b8b-ab7f-81e56fe6d2e9",
    "merchant_id": "1ed909ea-f561-4166-a8d8-50589e40ecc0",
    "environment": "SANDBOX",
    "currency": "NGN",
    "bank_name": "FCMB MFB",
    "bank_code": "090409",
    "account_name": "Dynamic Test Account",
    "account_number": "4097553750",
    "updated_at": "2025-09-26T10:24:12.562202Z",
    "created_at": "2025-09-26T10:24:12.562202Z",
    "booked_balance": 0,
    "available_balance": 0,
    "status": "ACTIVE",
    "updated": false,
    "user_id": null,
    "account_type": "DYNAMIC",
    "expiry_time": "2025-09-26T10:54:11.701702Z",
    "account_category": "CUSTOMER",
    "tier": ""
  }
}

Close static virtual account

Close Static Virtual Account

• Endpoint: POST /v1/accounts/static/close
• Description:
  Closes a static virtual account. This action disables the account, preventing any further transactions. Typically used when an account is no longer needed or needs to be deactivated for security reasons.
• Request Headers:
  • X-API-Key: Your API key for authentication.
• Request Body:
  • account_number (number, required): The static account number to be closed.
  • note (string, optional): A remark or reason for closing the account.

Method: DELETE

{{BASE_URL}}/accounts/static/close

Headers

Content-Type	Value
X-API-Key	X-API-Key

Body (raw)

{
  "account_number": 7000026062,
  "note": "for testing"
}

🔑 Authentication noauth

Param	value	Type

Response: 403

Response example:

{
  "success": false,
  "message": "account is closed - no operations can be performed on a closed account"
}

List accounts

List Virtual Accounts

• Endpoint: GET /v1/accounts
• Description:
  Retrieves a list of all virtual accounts (static and/or dynamic) associated with your API key. You can optionally filter the results by account type.
• Request Headers:
  • X-API-Key: Your API key for authentication.
• Query Parameters:
  • account_type (string, optional): Use STATIC to list only static accounts, or DYNAMIC to list only dynamic accounts.
• Examples:
  • List all accounts: GET /v1/accounts
  • List only static accounts: GET /v1/accounts?account_type=STATIC
  • List only dynamic accounts: GET /v1/accounts?account_type=DYNAMIC
• Response:
  • An array of account objects, each containing:
    • account_number
    • account_name
    • account_type (STATIC or DYNAMIC)
    • bank_name
    • status
    • reference (for dynamic accounts)
    • expiration_time (if applicable)
• Possible Status Codes:
  • 200 OK: Accounts retrieved successfully.
  • 400 Bad Request: Invalid account_type parameter.
  • 500 Internal Server Error: Failed to retrieve accounts.
• Note:
  • Pagination may be available depending on implementation. Consider checking for page and limit query parameters if supported.

Method: GET

{{BASE_URL}}/accounts

Headers

Content-Type	Value
X-API-Key	X-API-Key

Response: 200

Response example:

{
  "success": true,
  "message": "Accounts retrieved successfully",
  "data": [
    {
      "id": "6bcdc009-dbee-4000-b893-e4b2e7b9162a",
      "merchant_id": "d0c70a28-1023-484e-849f-3fb41cee743b",
      "environment": "SANDBOX",
      "currency": "NGN",
      "bank_name": "First City Monument Bank (FCMB)",
      "account_name": "Sandbox Account ONHKMF",
      "account_number": "9990012793",
      "account_type": "DYNAMIC",
      "account_category": "CUSTOMER",
      "status": "ACTIVE",
      "created_at": "2025-04-26T13:12:19.333674Z",
      "expiry_time": "2025-04-26T13:42:18.342752Z",
      "is_expired": true
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "totalItems": 1,
    "totalPages": 1
  }
}

Response: 200

Response example:

{
  "success": true,
  "message": "Accounts retrieved successfully",
  "data": [
    {
      "id": "76e9142c-12a1-4fdc-be18-80b4ff6a716a",
      "merchant_id": "d0c70a28-1023-484e-849f-3fb41cee743b",
      "environment": "SANDBOX",
      "currency": "NGN",
      "bank_name": "First City Monument Bank (FCMB)",
      "account_name": "Hassan Last",
      "account_number": "7000026062",
      "account_type": "STATIC",
      "account_category": "CUSTOMER",
      "status": "CLOSED",
      "created_at": "2025-04-26T14:36:45.015319Z",
      "expiry_time": null,
      "is_expired": false
    },
    {
      "id": "3be51c39-222d-433e-b35a-ade426f55b00",
      "merchant_id": "d0c70a28-1023-484e-849f-3fb41cee743b",
      "environment": "SANDBOX",
      "currency": "NGN",
      "bank_name": "First City Monument Bank (FCMB)",
      "account_name": "Hassan Last",
      "account_number": "7000025993",
      "account_type": "STATIC",
      "account_category": "CUSTOMER",
      "status": "ACTIVE",
      "created_at": "2025-04-26T13:45:26.211718Z",
      "expiry_time": null,
      "is_expired": false
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "totalItems": 2,
    "totalPages": 1
  }
}

Response: 200

Response example:

{
  "success": true,
  "message": "Accounts retrieved successfully",
  "data": [
    {
      "id": "76e9142c-12a1-4fdc-be18-80b4ff6a716a",
      "merchant_id": "d0c70a28-1023-484e-849f-3fb41cee743b",
      "environment": "SANDBOX",
      "currency": "NGN",
      "bank_name": "First City Monument Bank (FCMB)",
      "account_name": "Hassan Last",
      "account_number": "7000026062",
      "account_type": "STATIC",
      "account_category": "CUSTOMER",
      "status": "CLOSED",
      "created_at": "2025-04-26T14:36:45.015319Z",
      "expiry_time": null,
      "is_expired": false
    },
    {
      "id": "3be51c39-222d-433e-b35a-ade426f55b00",
      "merchant_id": "d0c70a28-1023-484e-849f-3fb41cee743b",
      "environment": "SANDBOX",
      "currency": "NGN",
      "bank_name": "First City Monument Bank (FCMB)",
      "account_name": "Hassan Last",
      "account_number": "7000025993",
      "account_type": "STATIC",
      "account_category": "CUSTOMER",
      "status": "ACTIVE",
      "created_at": "2025-04-26T13:45:26.211718Z",
      "expiry_time": null,
      "is_expired": false
    },
    {
      "id": "6bcdc009-dbee-4000-b893-e4b2e7b9162a",
      "merchant_id": "d0c70a28-1023-484e-849f-3fb41cee743b",
      "environment": "SANDBOX",
      "currency": "NGN",
      "bank_name": "First City Monument Bank (FCMB)",
      "account_name": "Sandbox Account ONHKMF",
      "account_number": "9990012793",
      "account_type": "DYNAMIC",
      "account_category": "CUSTOMER",
      "status": "ACTIVE",
      "created_at": "2025-04-26T13:12:19.333674Z",
      "expiry_time": "2025-04-26T13:42:18.342752Z",
      "is_expired": true
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "totalItems": 3,
    "totalPages": 1
  }
}