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"
}
'import requests
url = "https://api.payvessel.com/pms/api/external/request/customerReservedAccount/"
payload = {
"email": "johndoe@gmail.com",
"name": "JOHN DOE",
"phoneNumber": "09012345672",
"bankcode": ["999991", "120001"],
"account_type": "STATIC",
"businessid": "061C074E2F91F944B93993B4",
"bvn": "22345678901",
"nin": "12345678901"
}
headers = {
"api-key": "<api-key>",
"api-secret": "<api-secret>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'api-key': '<api-key>',
'api-secret': '<api-secret>',
'Content-Type': '<content-type>'
},
body: JSON.stringify({
email: 'johndoe@gmail.com',
name: 'JOHN DOE',
phoneNumber: '09012345672',
bankcode: ['999991', '120001'],
account_type: 'STATIC',
businessid: '061C074E2F91F944B93993B4',
bvn: '22345678901',
nin: '12345678901'
})
};
fetch('https://api.payvessel.com/pms/api/external/request/customerReservedAccount/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.payvessel.com/pms/api/external/request/customerReservedAccount/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => 'johndoe@gmail.com',
'name' => 'JOHN DOE',
'phoneNumber' => '09012345672',
'bankcode' => [
'999991',
'120001'
],
'account_type' => 'STATIC',
'businessid' => '061C074E2F91F944B93993B4',
'bvn' => '22345678901',
'nin' => '12345678901'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: <content-type>",
"api-key: <api-key>",
"api-secret: <api-secret>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.payvessel.com/pms/api/external/request/customerReservedAccount/"
payload := strings.NewReader("{\n \"email\": \"johndoe@gmail.com\",\n \"name\": \"JOHN DOE\",\n \"phoneNumber\": \"09012345672\",\n \"bankcode\": [\n \"999991\",\n \"120001\"\n ],\n \"account_type\": \"STATIC\",\n \"businessid\": \"061C074E2F91F944B93993B4\",\n \"bvn\": \"22345678901\",\n \"nin\": \"12345678901\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("api-key", "<api-key>")
req.Header.Add("api-secret", "<api-secret>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.payvessel.com/pms/api/external/request/customerReservedAccount/")
.header("api-key", "<api-key>")
.header("api-secret", "<api-secret>")
.header("Content-Type", "<content-type>")
.body("{\n \"email\": \"johndoe@gmail.com\",\n \"name\": \"JOHN DOE\",\n \"phoneNumber\": \"09012345672\",\n \"bankcode\": [\n \"999991\",\n \"120001\"\n ],\n \"account_type\": \"STATIC\",\n \"businessid\": \"061C074E2F91F944B93993B4\",\n \"bvn\": \"22345678901\",\n \"nin\": \"12345678901\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.payvessel.com/pms/api/external/request/customerReservedAccount/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["api-secret"] = '<api-secret>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"email\": \"johndoe@gmail.com\",\n \"name\": \"JOHN DOE\",\n \"phoneNumber\": \"09012345672\",\n \"bankcode\": [\n \"999991\",\n \"120001\"\n ],\n \"account_type\": \"STATIC\",\n \"businessid\": \"061C074E2F91F944B93993B4\",\n \"bvn\": \"22345678901\",\n \"nin\": \"12345678901\"\n}"
response = http.request(request)
puts response.read_body{
"status": true,
"service": "CREATE_VIRTUAL_ACCOUNT",
"business": "<string>",
"banks": [
{
"bankName": "<string>",
"accountNumber": "<string>",
"accountName": "<string>",
"account_type": "STATIC",
"trackingReference": "<string>",
"expire_date": "2023-11-07T05:31:56Z"
}
]
}{
"status": true,
"service": "CREATE_VIRTUAL_ACCOUNT",
"business": "061C074E2F91F944B93993B4",
"banks": [
{
"bankName": "9Payment Service Bank",
"accountNumber": "5030200545",
"accountName": "Payvessel-Merchant",
"account_type": "STATIC",
"expire_date": "2024-01-04T11:29:32.6522498+01:00",
"trackingReference": "40HTTGT96CDF360C3DRVGV3J"
},
{
"bankName": "PalmPay",
"accountNumber": "6030200545",
"accountName": "Payvessel-Merchant",
"account_type": "STATIC",
"expire_date": "2024-01-04T11:29:32.6522498+01:00",
"trackingReference": "50HTTGT96CDF360C3DRVGV3J"
}
]
}{
"status": false,
"service": "CREATE_VIRTUAL_ACCOUNT",
"message": "Invalid payload",
"errors": {
"bankcode": [
"At least one partner bank code is required"
],
"bvn": [
"BVN is mandatory for STATIC accounts"
]
}
}{
"error": 401,
"message": "Unauthorized. Please check your API key."
}{
"error": 123,
"message": "<string>"
}{
"error": 123,
"message": "<string>"
}{
"error": 123,
"message": "<string>"
}Virtual Accounts
Create Virtual Account
Virtual account API: create a STATIC or DYNAMIC Nigerian reserved bank account for customer collections.
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"
}
'import requests
url = "https://api.payvessel.com/pms/api/external/request/customerReservedAccount/"
payload = {
"email": "johndoe@gmail.com",
"name": "JOHN DOE",
"phoneNumber": "09012345672",
"bankcode": ["999991", "120001"],
"account_type": "STATIC",
"businessid": "061C074E2F91F944B93993B4",
"bvn": "22345678901",
"nin": "12345678901"
}
headers = {
"api-key": "<api-key>",
"api-secret": "<api-secret>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'api-key': '<api-key>',
'api-secret': '<api-secret>',
'Content-Type': '<content-type>'
},
body: JSON.stringify({
email: 'johndoe@gmail.com',
name: 'JOHN DOE',
phoneNumber: '09012345672',
bankcode: ['999991', '120001'],
account_type: 'STATIC',
businessid: '061C074E2F91F944B93993B4',
bvn: '22345678901',
nin: '12345678901'
})
};
fetch('https://api.payvessel.com/pms/api/external/request/customerReservedAccount/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.payvessel.com/pms/api/external/request/customerReservedAccount/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => 'johndoe@gmail.com',
'name' => 'JOHN DOE',
'phoneNumber' => '09012345672',
'bankcode' => [
'999991',
'120001'
],
'account_type' => 'STATIC',
'businessid' => '061C074E2F91F944B93993B4',
'bvn' => '22345678901',
'nin' => '12345678901'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: <content-type>",
"api-key: <api-key>",
"api-secret: <api-secret>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.payvessel.com/pms/api/external/request/customerReservedAccount/"
payload := strings.NewReader("{\n \"email\": \"johndoe@gmail.com\",\n \"name\": \"JOHN DOE\",\n \"phoneNumber\": \"09012345672\",\n \"bankcode\": [\n \"999991\",\n \"120001\"\n ],\n \"account_type\": \"STATIC\",\n \"businessid\": \"061C074E2F91F944B93993B4\",\n \"bvn\": \"22345678901\",\n \"nin\": \"12345678901\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("api-key", "<api-key>")
req.Header.Add("api-secret", "<api-secret>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.payvessel.com/pms/api/external/request/customerReservedAccount/")
.header("api-key", "<api-key>")
.header("api-secret", "<api-secret>")
.header("Content-Type", "<content-type>")
.body("{\n \"email\": \"johndoe@gmail.com\",\n \"name\": \"JOHN DOE\",\n \"phoneNumber\": \"09012345672\",\n \"bankcode\": [\n \"999991\",\n \"120001\"\n ],\n \"account_type\": \"STATIC\",\n \"businessid\": \"061C074E2F91F944B93993B4\",\n \"bvn\": \"22345678901\",\n \"nin\": \"12345678901\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.payvessel.com/pms/api/external/request/customerReservedAccount/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["api-secret"] = '<api-secret>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"email\": \"johndoe@gmail.com\",\n \"name\": \"JOHN DOE\",\n \"phoneNumber\": \"09012345672\",\n \"bankcode\": [\n \"999991\",\n \"120001\"\n ],\n \"account_type\": \"STATIC\",\n \"businessid\": \"061C074E2F91F944B93993B4\",\n \"bvn\": \"22345678901\",\n \"nin\": \"12345678901\"\n}"
response = http.request(request)
puts response.read_body{
"status": true,
"service": "CREATE_VIRTUAL_ACCOUNT",
"business": "<string>",
"banks": [
{
"bankName": "<string>",
"accountNumber": "<string>",
"accountName": "<string>",
"account_type": "STATIC",
"trackingReference": "<string>",
"expire_date": "2023-11-07T05:31:56Z"
}
]
}{
"status": true,
"service": "CREATE_VIRTUAL_ACCOUNT",
"business": "061C074E2F91F944B93993B4",
"banks": [
{
"bankName": "9Payment Service Bank",
"accountNumber": "5030200545",
"accountName": "Payvessel-Merchant",
"account_type": "STATIC",
"expire_date": "2024-01-04T11:29:32.6522498+01:00",
"trackingReference": "40HTTGT96CDF360C3DRVGV3J"
},
{
"bankName": "PalmPay",
"accountNumber": "6030200545",
"accountName": "Payvessel-Merchant",
"account_type": "STATIC",
"expire_date": "2024-01-04T11:29:32.6522498+01:00",
"trackingReference": "50HTTGT96CDF360C3DRVGV3J"
}
]
}{
"status": false,
"service": "CREATE_VIRTUAL_ACCOUNT",
"message": "Invalid payload",
"errors": {
"bankcode": [
"At least one partner bank code is required"
],
"bvn": [
"BVN is mandatory for STATIC accounts"
]
}
}{
"error": 401,
"message": "Unauthorized. Please check your API key."
}{
"error": 123,
"message": "<string>"
}{
"error": 123,
"message": "<string>"
}{
"error": 123,
"message": "<string>"
}Create a reserved virtual bank account (STATIC or DYNAMIC). Authentication is covered in Authentication.
Supported Banks:
For a 9PSB or Palmpay STATIC account with KYC:
Example request body (DYNAMIC):
Both 9PSB and Palmpay support DYNAMIC accounts without KYC:
or
Example response for PalmPay (DYNAMIC):
Example response for 9Payment Service Bank (DYNAMIC):
cURL:
For concepts and when to use STATIC vs DYNAMIC, see the Customer Reserved Account guide.
- PalmPay (
999991): Requires BVN/NIN for both STATIC and DYNAMIC accounts - 9Payment Service Bank (
120001): For STATIC accounts, KYC is optional (30k daily limit); for DYNAMIC accounts, no KYC required
{
"email": "johndoe@gmail.com",
"name": "JOHN DOE",
"phoneNumber": "09012345672",
"bankcode": ["120001"],
"account_type": "STATIC",
"businessid": "061C074E2F91F944B93993B4"
}
{
"email": "johndoe@gmail.com",
"name": "JOHN DOE",
"phoneNumber": "09012345672",
"bankcode": ["999991", "120001"],
"account_type": "STATIC",
"businessid": "061C074E2F91F944B93993B4",
"bvn": "22345678901",
"nin": "12345678901"
}
{
"email": "customer@example.com",
"name": "JANE DOE",
"phoneNumber": "08012345678",
"bankcode": ["999991"],
"account_type": "DYNAMIC",
"businessid": "061C074E2F91F944B93993B4"
}
{
"email": "customer@example.com",
"name": "JANE DOE",
"phoneNumber": "08012345678",
"bankcode": ["120001"],
"account_type": "DYNAMIC",
"businessid": "061C074E2F91F944B93993B4"
}
{
"status": true,
"service": "CREATE_VIRTUAL_ACCOUNT",
"business": "061C074E2F91F944B93993B4",
"banks": {
"bankCode": "999991",
"bankName": "PalmPay",
"accountNumber": "8880314352",
"accountName": "Demo User",
"account_type": "DYNAMIC",
"expire_date": "2026-05-15T11:49:36.117753+01:00",
"trackingReference": "XOINFKVRO90311273BD8DZZ8"
}
}
{
"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 -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":["120001"],"account_type":"STATIC","businessid":"YOUR_BUSINESS_ID"}'
Upgrading 9PSB Static Accounts
When a customer’s 9PSB static account (created without BVN/NIN) reaches its 30k daily limit, they must provide their BVN and NIN to remove the restriction. Use the Update Virtual Account endpoint to upgrade the account.Headers
Your Payvessel public API key
Your Payvessel secret
Request content type
Available options:
application/json Body
application/json
Customer email address
Customer full name (first name and last name)
Customer phone number in international format
List of partner bank codes to provision the virtual account with
Available options:
999991, 120001 Example:
["999991", "120001"]
Type of virtual account to create
Available options:
STATIC, DYNAMIC Merchant business ID supplied by Payvessel
Customer Bank Verification Number (required for STATIC accounts)
Customer National Identification Number (use when BVN is unavailable)