> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rolla.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# 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) rather than creating a duplicate.
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](/api-reference/webhooks/overview) 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.
This endpoint is **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. 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
```bash theme={null}
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
```json theme={null}
{
"status": 201,
"success": true,
"message": "Customer virtual account generated successfully",
"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.
## OpenAPI
````yaml POST /wallet/virtual-accounts/generate/customer
openapi: 3.1.0
info:
title: Rolla Developer API
description: >-
API for programmatic transaction management on the Rolla platform. Monetary
`amount` fields use the smallest unit of the referenced currency unless an
endpoint says otherwise (e.g. NGN = kobo, USD = cents, where **100 cents =
USD 1.00**).
version: 1.0.0
servers:
- url: https://api.rolla.xyz/api/v1/external
description: Production server
security:
- apiKeyAuth: []
paths:
/wallet/virtual-accounts/generate/customer:
post:
summary: Generate Customer Virtual Account
description: >-
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) rather
than creating a duplicate.
operationId: generateCustomerVirtualAccount
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- first_name
- last_name
- email
- phone
- bvn
- date_of_birth
- address
- gender
properties:
customer_identifier:
type: string
description: >-
Your own unique id for this end-user. Pass it so the account
maps back to the user and re-requests are idempotent. If
omitted, one is generated and returned.
example: user-12345
first_name:
type: string
example: Tosin
last_name:
type: string
example: Kalejaiye
email:
type: string
format: email
example: tosin@example.com
phone:
type: string
description: Nigerian mobile number.
example: '08012345678'
bvn:
type: string
description: >-
End-user's 11-digit Bank Verification Number. Validated by
the provider. Never returned in responses.
example: '22222222222'
date_of_birth:
type: string
description: End-user's date of birth in mm/dd/yyyy format.
example: 01/31/1990
address:
type: string
example: 12 Marina Road, Lagos
gender:
type: string
enum:
- '1'
- '2'
description: 1 = male, 2 = female.
example: '1'
responses:
'200':
description: >-
An account already existed for this customer_identifier and was
returned unchanged
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 200
success:
type: boolean
example: true
message:
type: string
example: >-
Customer virtual account already exists for this
customer_identifier
data:
type: object
properties:
virtualAccount:
type: object
properties:
id:
type: string
format: uuid
customer_identifier:
type: string
example: user-12345
first_name:
type: string
example: Tosin
last_name:
type: string
example: Kalejaiye
email:
type: string
example: tosin@example.com
phone:
type: string
example: '08012345678'
bvn_last4:
type: string
example: '2222'
description: >-
Last 4 digits of the BVN. The full BVN is never
returned.
currency:
type: string
example: NGN
bank_name:
type: string
example: GTBank
bank_code:
type: string
example: '058'
account_number:
type: string
example: '4382272943'
account_name:
type: string
example: Tosin Kalejaiye
status:
type: string
example: active
created_at:
type: string
format: date-time
existing:
type: boolean
description: >-
true when an account already existed for this
customer_identifier and was returned unchanged
(idempotent); false when newly created.
example: true
'201':
description: New customer virtual account created
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 201
success:
type: boolean
example: true
message:
type: string
example: Customer virtual account generated successfully
data:
type: object
properties:
virtualAccount:
type: object
properties:
id:
type: string
format: uuid
customer_identifier:
type: string
example: user-12345
first_name:
type: string
example: Tosin
last_name:
type: string
example: Kalejaiye
email:
type: string
example: tosin@example.com
phone:
type: string
example: '08012345678'
bvn_last4:
type: string
example: '2222'
description: >-
Last 4 digits of the BVN. The full BVN is never
returned.
currency:
type: string
example: NGN
bank_name:
type: string
example: GTBank
bank_code:
type: string
example: '058'
account_number:
type: string
example: '4382272943'
account_name:
type: string
example: Tosin Kalejaiye
status:
type: string
example: active
created_at:
type: string
format: date-time
existing:
type: boolean
description: >-
true when an account already existed for this
customer_identifier and was returned unchanged
(idempotent); false when newly created.
example: false
'400':
description: Validation error or provider rejection (e.g. invalid BVN)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Error:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Your Rolla API key
````