Skip to main content
Use this endpoint to generate a unique virtual account number for a single payment collection. You specify a pool account to receive the funds — when your customer pays into the virtual account, the core banking system automatically sweeps the balance into that pool account. This pattern is useful for per-invoice or per-order payment tracking, since each virtual account can carry a descriptive name for easy reconciliation. Endpoint 
POST https://baasapi.payrepmfb.com/api/v1/account/api/create_virtual_account
Sandbox 
POST https://shogun-dev.xchangeboxng.com/api/v1/account/api/create_virtual_account

​
Authentication

Include your Bearer token in the Authorization header: 
Authorization: Bearer <access_token>
Obtain a token from Generate Token.

​
Request body

​
pool_account_number
string
required
The account number that will receive funds when this virtual account is credited. Must be a valid current or pool account that belongs to your business. Maximum 10 characters.
​
account_name
string
A label for this virtual account — for example, "Invoice #12345" or "Order #9876". Defaults to "Virtual Dynamic Account" if omitted. Maximum 255 characters.
​
account_type
string
Set to "virtual". This field identifies the account class being created.

​
Example request

curl --request POST \
  --url https://baasapi.payrepmfb.com/api/v1/account/api/create_virtual_account \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "account_type": "virtual",
    "account_name": "Invoice #12345",
    "pool_account_number": "7801234567"
  }'

​
Response

​
Success

{
  "status": true,
  "response_code": "00",
  "message": "Virtual account created successfully",
  "data": {
    "account_number": "9901234567",
    "account_name": "Invoice #12345",
    "account_type": "virtual",
    "status": "active",
    "balance": "0.000000000",
    "last_balance_update": null
  }
}
​
data.account_number
string
The unique account number to share with your customer for payment. Once credited, funds move automatically to the configured pool account.
​
data.account_name
string
The label assigned to this virtual account.
​
data.account_type
string
Always "virtual" for accounts created by this endpoint.
​
data.status
string
"active" — the account is ready to receive a payment.
​
data.balance
string
Current balance in NGN. Starts at "0.000000000" and sweeps to the pool account on credit.
​
data.last_balance_update
string | null
ISO 8601 timestamp of the most recent balance event, or null if no payments have been received.

​
Error — pool account not found

{
  "status": false,
  "response_code": "42",
  "message": "Can not find pool account",
  "data": null
}

​
Error codes

CodeMeaning
00Success
41Customer not found — your API credentials are invalid
61Customer not verified — your business account must be active
42Pool account not found — the pool_account_number does not belong to your business
80Service unavailable — the core banking provider is temporarily down
83Provider error — the core banking system rejected the request
Virtual accounts settle automatically. You do not need to initiate a transfer — any payment credited to the virtual account is swept to the parent pool account by the core banking system immediately upon receipt.