Fixed Accounts

Fixed virtual accounts are permanent accounts assigned to your business that can receive payments from customers.

API Reference

Create Fixed Account

• Path: /api/v1/virtual-accounts/fixed-account
• Method: POST

Request Body Table

Field	Type	Required	Description
customer	object	Yes	Customer information
customer.name	string	Yes	Customer's full name
customer.email	string	Yes	Customer's email address
customer.phone	string	Yes	Customer's phone number
customer.externalId	string	No	For merchant customer identification
customer.address	object	No	Customer's address information
customer.address.line1	string	Yes	Address line 1
customer.address.line2	string	No	Address line 2
customer.address.city	string	Yes	City
customer.address.state	string	Yes	State
customer.address.postalCode	string	No	Postal code
customer.address.countryCode	string	Yes	Alpha-2 country code
customer.nin	string	No	National Identification Number
customer.bvn	string	Yes	Bank Verification Number
reference	string	Yes	Unique reference for the transaction
dob	date-string	Yes	Date of birth (format: YYYY-MM-DD)
notificationUrl	string	No	An optional notification URL. If one isn't specified, it will be directed to the default webhook URL configured on the Merchant Dashboard
narration	string	No	Description for the account
businessId	string	Yes	Your business identifier

Request Body:

{
  "customer": {
    "name": "Test Customer",
    "email": "test@customer.com",
    "address": {
      "line1": "No. 9 Financial Avenue Off Main Road, Payonus, Finance"
    },
    "bvn": "22123456789",
    "phone": "+2347019098867"
  },
  "dob": "1994-01-01",
  "businessId": "{your_business_id}",
  "reference": "{unique_reference}"
}

Response Body:

{
  "status": 200,
  "message": "Success",
  "data": {
    "accountName": "Test Customer",
    "accountNumber": "1010101010",
    "bankName": "Test Bank"
  }
}

List Fixed Accounts

• Path: /api/v1/virtual-accounts/fixed-accounts
• Method: GET
• Query Params:
  • accountNumber: string
  • businessIds: string (array)
  • createdFrom: date
  • createdTo: date
• Response Body:
  • pageNo: number
  • pageSize: number
  • lastPage: number
  • totalNumberOfItems: number
  • content: (collection)
    • id: string
    • accountNumber: string
    • accountName: string
    • paymentGateway: string
    • accountType: string - valid types: PAYIN, PAYOUT
    • bankName: string
    • email: string
    • businessId: string
    • mobileNumber: string
    • address: string
    • deleted: boolean
    • createdDate: date-string
    • merchantReference: string

Usage

Fixed accounts are ideal for: - Recurring payments - Long-term customer relationships - Businesses that need dedicated payment accounts

Notes

• Fixed accounts do not expire and can be used for multiple transactions
• You will receive webhook notifications for all payments made to the fixed account
• The account details can be shared with multiple customers or integrated into your payment systems
• You can verify the status of a specific payment using the Verify Single Payment endpoint with the onusReference.