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>",
"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>",
"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.
Example request body (STATIC):
Example request body (DYNAMIC):
You can specify either Rubies MFB or 9Payment Service Bank for the dynamic account:
or
Example response for Rubies MFB (DYNAMIC):
Example response for 9Payment Service Bank (DYNAMIC):
cURL:
For concepts and when to use STATIC vs DYNAMIC, see the Customer Reserved Account guide.
{
"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": ["090175"],
"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": "090175",
"bankName": "Rubies MFB",
"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":["999991","120001"],"account_type":"STATIC","businessid":"YOUR_BUSINESS_ID","bvn":"22345678901"}'
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)
⌘I