Generate Customer Virtual Account
curl --request POST \
--url https://api.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"customer_identifier": "user-12345",
"first_name": "Tosin",
"last_name": "Kalejaiye",
"email": "tosin@example.com",
"phone": "08012345678",
"bvn": "22222222222",
"date_of_birth": "01/31/1990",
"address": "12 Marina Road, Lagos",
"gender": "1"
}
'import requests
url = "https://api.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer"
payload = {
"customer_identifier": "user-12345",
"first_name": "Tosin",
"last_name": "Kalejaiye",
"email": "tosin@example.com",
"phone": "08012345678",
"bvn": "22222222222",
"date_of_birth": "01/31/1990",
"address": "12 Marina Road, Lagos",
"gender": "1"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
customer_identifier: 'user-12345',
first_name: 'Tosin',
last_name: 'Kalejaiye',
email: 'tosin@example.com',
phone: '08012345678',
bvn: '22222222222',
date_of_birth: '01/31/1990',
address: '12 Marina Road, Lagos',
gender: '1'
})
};
fetch('https://api.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer', 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.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer",
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([
'customer_identifier' => 'user-12345',
'first_name' => 'Tosin',
'last_name' => 'Kalejaiye',
'email' => 'tosin@example.com',
'phone' => '08012345678',
'bvn' => '22222222222',
'date_of_birth' => '01/31/1990',
'address' => '12 Marina Road, Lagos',
'gender' => '1'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$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.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer"
payload := strings.NewReader("{\n \"customer_identifier\": \"user-12345\",\n \"first_name\": \"Tosin\",\n \"last_name\": \"Kalejaiye\",\n \"email\": \"tosin@example.com\",\n \"phone\": \"08012345678\",\n \"bvn\": \"22222222222\",\n \"date_of_birth\": \"01/31/1990\",\n \"address\": \"12 Marina Road, Lagos\",\n \"gender\": \"1\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
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.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"customer_identifier\": \"user-12345\",\n \"first_name\": \"Tosin\",\n \"last_name\": \"Kalejaiye\",\n \"email\": \"tosin@example.com\",\n \"phone\": \"08012345678\",\n \"bvn\": \"22222222222\",\n \"date_of_birth\": \"01/31/1990\",\n \"address\": \"12 Marina Road, Lagos\",\n \"gender\": \"1\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customer_identifier\": \"user-12345\",\n \"first_name\": \"Tosin\",\n \"last_name\": \"Kalejaiye\",\n \"email\": \"tosin@example.com\",\n \"phone\": \"08012345678\",\n \"bvn\": \"22222222222\",\n \"date_of_birth\": \"01/31/1990\",\n \"address\": \"12 Marina Road, Lagos\",\n \"gender\": \"1\"\n}"
response = http.request(request)
puts response.read_body{
"status": 200,
"message": "Customer virtual account already exists for this customer_identifier",
"success": true,
"data": {
"virtualAccount": {
"id": "9632c120-3c98-4a1c-baf2-47c17a079802",
"customer_identifier": "user-12345",
"first_name": "Tosin",
"last_name": "Kalejaiye",
"email": "tosin@example.com",
"phone": "08012345678",
"bvn_last4": "2222",
"currency": "NGN",
"bank_name": "GTBank",
"bank_code": "058",
"account_number": "4382272943",
"account_name": "Tosin Kalejaiye",
"status": "active",
"created_at": "2026-07-10T10:02:11.942Z"
},
"existing": true
}
}{
"status": 201,
"message": "Customer virtual account generated successfully",
"success": true,
"data": {
"virtualAccount": {
"id": "9632c120-3c98-4a1c-baf2-47c17a079802",
"customer_identifier": "user-12345",
"first_name": "Tosin",
"last_name": "Kalejaiye",
"email": "tosin@example.com",
"phone": "08012345678",
"bvn_last4": "2222",
"currency": "NGN",
"bank_name": "GTBank",
"bank_code": "058",
"account_number": "4382272943",
"account_name": "Tosin Kalejaiye",
"status": "active",
"created_at": "2026-07-10T10:02:11.942Z"
},
"existing": false
}
}{
"status": 400,
"message": "Validation failed",
"errors": [
{
"path": [
"bvn"
],
"message": "Bvn: bvn must be exactly 11 digits"
}
]
}{
"status": 400,
"message": "Validation failed",
"code": "ACCOUNT_RESTRICTED",
"errors": [
{
"path": [
"amount"
],
"message": "amount must be a whole number of smallest currency units (e.g. cents)"
}
]
}Deposits & Virtual Accounts
Generate Customer Virtual Account
Creates (or returns the existing) permanent NGN virtual account dedicated to one of your end-users, so deposits to it can be attributed to that user via webhook. The provider requires the end-user’s BVN, name and date of birth. Idempotent per customer_identifier: re-requesting for the same customer returns the account already on file (HTTP 200, existing: true) rather than creating a duplicate.
POST
/
wallet
/
virtual-accounts
/
generate
/
customer
Generate Customer Virtual Account
curl --request POST \
--url https://api.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"customer_identifier": "user-12345",
"first_name": "Tosin",
"last_name": "Kalejaiye",
"email": "tosin@example.com",
"phone": "08012345678",
"bvn": "22222222222",
"date_of_birth": "01/31/1990",
"address": "12 Marina Road, Lagos",
"gender": "1"
}
'import requests
url = "https://api.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer"
payload = {
"customer_identifier": "user-12345",
"first_name": "Tosin",
"last_name": "Kalejaiye",
"email": "tosin@example.com",
"phone": "08012345678",
"bvn": "22222222222",
"date_of_birth": "01/31/1990",
"address": "12 Marina Road, Lagos",
"gender": "1"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
customer_identifier: 'user-12345',
first_name: 'Tosin',
last_name: 'Kalejaiye',
email: 'tosin@example.com',
phone: '08012345678',
bvn: '22222222222',
date_of_birth: '01/31/1990',
address: '12 Marina Road, Lagos',
gender: '1'
})
};
fetch('https://api.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer', 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.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer",
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([
'customer_identifier' => 'user-12345',
'first_name' => 'Tosin',
'last_name' => 'Kalejaiye',
'email' => 'tosin@example.com',
'phone' => '08012345678',
'bvn' => '22222222222',
'date_of_birth' => '01/31/1990',
'address' => '12 Marina Road, Lagos',
'gender' => '1'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$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.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer"
payload := strings.NewReader("{\n \"customer_identifier\": \"user-12345\",\n \"first_name\": \"Tosin\",\n \"last_name\": \"Kalejaiye\",\n \"email\": \"tosin@example.com\",\n \"phone\": \"08012345678\",\n \"bvn\": \"22222222222\",\n \"date_of_birth\": \"01/31/1990\",\n \"address\": \"12 Marina Road, Lagos\",\n \"gender\": \"1\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
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.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"customer_identifier\": \"user-12345\",\n \"first_name\": \"Tosin\",\n \"last_name\": \"Kalejaiye\",\n \"email\": \"tosin@example.com\",\n \"phone\": \"08012345678\",\n \"bvn\": \"22222222222\",\n \"date_of_birth\": \"01/31/1990\",\n \"address\": \"12 Marina Road, Lagos\",\n \"gender\": \"1\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customer_identifier\": \"user-12345\",\n \"first_name\": \"Tosin\",\n \"last_name\": \"Kalejaiye\",\n \"email\": \"tosin@example.com\",\n \"phone\": \"08012345678\",\n \"bvn\": \"22222222222\",\n \"date_of_birth\": \"01/31/1990\",\n \"address\": \"12 Marina Road, Lagos\",\n \"gender\": \"1\"\n}"
response = http.request(request)
puts response.read_body{
"status": 200,
"message": "Customer virtual account already exists for this customer_identifier",
"success": true,
"data": {
"virtualAccount": {
"id": "9632c120-3c98-4a1c-baf2-47c17a079802",
"customer_identifier": "user-12345",
"first_name": "Tosin",
"last_name": "Kalejaiye",
"email": "tosin@example.com",
"phone": "08012345678",
"bvn_last4": "2222",
"currency": "NGN",
"bank_name": "GTBank",
"bank_code": "058",
"account_number": "4382272943",
"account_name": "Tosin Kalejaiye",
"status": "active",
"created_at": "2026-07-10T10:02:11.942Z"
},
"existing": true
}
}{
"status": 201,
"message": "Customer virtual account generated successfully",
"success": true,
"data": {
"virtualAccount": {
"id": "9632c120-3c98-4a1c-baf2-47c17a079802",
"customer_identifier": "user-12345",
"first_name": "Tosin",
"last_name": "Kalejaiye",
"email": "tosin@example.com",
"phone": "08012345678",
"bvn_last4": "2222",
"currency": "NGN",
"bank_name": "GTBank",
"bank_code": "058",
"account_number": "4382272943",
"account_name": "Tosin Kalejaiye",
"status": "active",
"created_at": "2026-07-10T10:02:11.942Z"
},
"existing": false
}
}{
"status": 400,
"message": "Validation failed",
"errors": [
{
"path": [
"bvn"
],
"message": "Bvn: bvn must be exactly 11 digits"
}
]
}{
"status": 400,
"message": "Validation failed",
"code": "ACCOUNT_RESTRICTED",
"errors": [
{
"path": [
"amount"
],
"message": "amount must be a whole number of smallest currency units (e.g. cents)"
}
]
}Create a permanent NGN virtual account dedicated to one of your end-users. Each user gets their own account number, so when a deposit lands you can attribute it to the right user via webhook and credit them automatically — instead of everyone sharing a single business account.
The provider requires the end-user’s BVN, name and date of birth to open a dedicated personal account.
Your own unique id for the end-user (their user id in your system). It is what ties the Rolla account back to a specific user, so the deposit webhook tells you who paid. Pass your own value; if you omit it, one is generated and returned.
This endpoint is idempotent per
customer_identifier. Re-requesting for the same customer returns the account already on file rather than creating a duplicate: HTTP 200 with "message": "Customer virtual account already exists for this customer_identifier" and existing: true, against HTTP 201 and existing: false when a new account is minted. Use a new customer_identifier to create a new account for a different user.customer_identifier
Your own unique id for the end-user (their user id in your system). It is what ties the Rolla account back to a specific user, so the deposit webhook tells you who paid. Pass your own value; if you omit it, one is generated and returned.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
customer_identifier | string | No | Your unique id for this end-user. Omit to have one generated. |
first_name | string | Yes | End-user’s first name |
last_name | string | Yes | End-user’s last name |
email | string | Yes | End-user’s email |
phone | string | Yes | End-user’s Nigerian mobile number |
bvn | string | Yes | End-user’s 11-digit BVN. Validated by the provider. Never returned in responses. |
date_of_birth | string | Yes | End-user’s date of birth in mm/dd/yyyy format |
address | string | Yes | End-user’s address |
gender | string | Yes | "1" = male, "2" = female |
Example Request
curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"customer_identifier": "user-12345",
"first_name": "Tosin",
"last_name": "Kalejaiye",
"email": "tosin@example.com",
"phone": "08012345678",
"bvn": "22222222222",
"date_of_birth": "01/31/1990",
"address": "12 Marina Road, Lagos",
"gender": "1"
}'
Example Response
{
"status": 201,
"message": "Customer virtual account generated successfully",
"success": true,
"data": {
"virtualAccount": {
"id": "9632c120-3c98-4a1c-baf2-47c17a079802",
"customer_identifier": "user-12345",
"first_name": "Tosin",
"last_name": "Kalejaiye",
"email": "tosin@example.com",
"phone": "08012345678",
"bvn_last4": "2222",
"currency": "NGN",
"bank_name": "GTBank",
"bank_code": "058",
"account_number": "4382272943",
"account_name": "Tosin Kalejaiye",
"status": "active",
"created_at": "2026-07-10T10:02:11.942Z"
},
"existing": false
}
}
The raw BVN is never echoed back — only
bvn_last4. In the sandbox, use the test BVN 22222222222; a made-up value returns 400 "invalid BVN". In production, pass the user’s real BVN.If your API key has an IP allowlist configured, it applies here as it does to every endpoint — requests from other IPs are rejected. An allowlist is not required to use this endpoint.
Authorizations
Your Rolla API key
Body
application/json
Required string length:
1 - 100Example:
"Tosin"
Required string length:
1 - 100Example:
"Kalejaiye"
Example:
"tosin@example.com"
Nigerian mobile number.
Required string length:
10 - 20Example:
"08012345678"
End-user's 11-digit Bank Verification Number. Validated by the provider. Never returned in responses.
Pattern:
^\d{11}$Example:
"22222222222"
End-user's date of birth in mm/dd/yyyy format.
Pattern:
^\d{2}/\d{2}/\d{4}$Example:
"01/31/1990"
Required string length:
1 - 255Example:
"12 Marina Road, Lagos"
1 = male, 2 = female.
Available options:
1, 2 Example:
"1"
Your own unique id for this end-user. Pass it so the account maps back to the user and re-requests are idempotent; omit it and one is generated and returned.
Required string length:
1 - 100Example:
"user-12345"