Skip to main content
POST
/
pms
/
api
/
external
/
request
/
customerReservedAccount
/
Create Virtual Account
curl --request POST \
  --url https://api.payvessel.com/pms/api/external/request/customerReservedAccount/ \
  --header 'Content-Type: <content-type>' \
  --header 'api-key: <api-key>' \
  --header 'api-secret: <api-secret>' \
  --data '
{
  "email": "johndoe@gmail.com",
  "name": "JOHN DOE",
  "phoneNumber": "09012345672",
  "bankcode": [
    "999991",
    "120001"
  ],
  "account_type": "STATIC",
  "businessid": "061C074E2F91F944B93993B4",
  "bvn": "22345678901",
  "nin": "12345678901"
}
'
{
  "status": true,
  "service": "CREATE_VIRTUAL_ACCOUNT",
  "business": "<string>",
  "banks": [
    {
      "bankName": "<string>",
      "accountNumber": "<string>",
      "accountName": "<string>",
      "trackingReference": "<string>",
      "expire_date": "2023-11-07T05:31:56Z"
    }
  ]
}
Create a reserved virtual bank account (STATIC or DYNAMIC). Authentication is covered in Authentication. Example request body (STATIC): 
{
  "email": "johndoe@gmail.com",
  "name": "JOHN DOE",
  "phoneNumber": "09012345672",
  "bankcode": ["999991", "120001"],
  "account_type": "STATIC",
  "businessid": "061C074E2F91F944B93993B4",
  "bvn": "22345678901",
  "nin": "12345678901"
}
Example request body (DYNAMIC): You can specify either Rubies MFB or 9Payment Service Bank for the dynamic account: 
{
  "email": "customer@example.com",
  "name": "JANE DOE",
  "phoneNumber": "08012345678",
  "bankcode": ["090175"],
  "account_type": "DYNAMIC",
  "businessid": "061C074E2F91F944B93993B4"
}
or 
{
  "email": "customer@example.com",
  "name": "JANE DOE",
  "phoneNumber": "08012345678",
  "bankcode": ["120001"],
  "account_type": "DYNAMIC",
  "businessid": "061C074E2F91F944B93993B4"
}
Example response for Rubies MFB (DYNAMIC): 
{
  "status": true,
  "service": "CREATE_VIRTUAL_ACCOUNT",
  "business": "061C074E2F91F944B93993B4",
  "banks": {
    "bankCode": "090175",
    "bankName": "Rubies MFB",
    "accountNumber": "8880314352",
    "accountName": "Demo User",
    "account_type": "DYNAMIC",
    "expire_date": "2026-05-15T11:49:36.117753+01:00",
    "trackingReference": "XOINFKVRO90311273BD8DZZ8"
  }
}
Example response for 9Payment Service Bank (DYNAMIC): 
{
  "status": true,
  "service": "CREATE_VIRTUAL_ACCOUNT",
  "business": "061C074E2F91F944B93993B4",
  "banks": {
    "bankCode": "120001",
    "bankName": "9Payment Service Bank",
    "accountNumber": "5030200545",
    "accountName": "Demo User",
    "account_type": "DYNAMIC",
    "expire_date": "2026-05-15T11:49:36.117753+01:00",
    "trackingReference": "YOINFKVRO90311273BD8DZZ9"
  }
}
cURL: 
curl -X POST "https://api.payvessel.com/pms/api/external/request/customerReservedAccount/" \
  -H "api-key: YOUR_API_KEY" \
  -H "api-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email":"johndoe@gmail.com","name":"JOHN DOE","phoneNumber":"09012345672","bankcode":["999991","120001"],"account_type":"STATIC","businessid":"YOUR_BUSINESS_ID","bvn":"22345678901"}'
For concepts and when to use STATIC vs DYNAMIC, see the Customer Reserved Account guide.

Headers

​
api-key
string
required

Your Payvessel public API key

​
api-secret
string
required

Your Payvessel secret

​
Content-Type
enum<string>
required

Request content type

Available options:
application/json

Body

application/json
​
email
string<email>
required

Customer email address

​
name
string
required

Customer full name (first name and last name)

​
phoneNumber
string
required

Customer phone number in international format

​
bankcode
enum<string>[]
required

List of partner bank codes to provision the virtual account with

Available options:
999991,
120001
Example:
["999991", "120001"]
​
account_type
enum<string>
required

Type of virtual account to create

Available options:
STATIC,
DYNAMIC
​
businessid
string
required

Merchant business ID supplied by Payvessel

​
bvn
string

Customer Bank Verification Number (required for STATIC accounts)

​
nin
string

Customer National Identification Number (use when BVN is unavailable)

Response

Virtual account created successfully

​
status
boolean
required

Indicates whether the request succeeded

​
service
string
required

Operation identifier

Example:

"CREATE_VIRTUAL_ACCOUNT"

​
business
string
required

Merchant business ID

​
banks
object[]
required

Generated virtual bank accounts