Virtual accounts

Create account

Issues a virtual account and returns the details your customer pays into.

POST /v1/create_account

Headers

Header	Value
Content-Type	`application/json`
api-key	Your business API key
secret-key	Your business secret key

Request body

Field	Type	Required	Notes
email	string	Yes	The customer this account belongs to.
ref	string	Yes	Your own reference, returned as `client_reference` everywhere the account appears.
fname	string	Yes	First name.
lname	string	Yes	Last name.
phone	number	Yes	Customer phone number.
bvn	number	Yes	Required by some banking partners before an account can be issued.
dob	string	Yes	Date of birth.
gender	string	Yes	Customer gender.
address	string	Yes	Customer address.
banks	array	Yes	Which partner banks to issue with. ["9PSB"]

Request

Example

curl -X POST /v1/create_account \
  -H "Content-Type: application/json" \
  -H "api-key: <your api key>" \
  -H "secret-key: <your secret key>" \
-d '{
    "email": "customer@example.com",
    "ref": "order_10432",
    "fname": "Amanda",
    "lname": "Elumelu",
    "phone": 8060082079,
    "bvn": 22222222222,
    "dob": "1995-05-15",
    "gender": "female",
    "address": "12 Marina Road, Lagos",
    "banks": ["9PSB"]
  }'

{
  "email":   "customer@example.com",
  "ref":     "order_10432",
  "fname":   "Amanda",
  "lname":   "Elumelu",
  "phone":   8060082079,
  "bvn":     22222222222,
  "dob":     "1995-05-15",
  "gender":  "female",
  "address": "12 Marina Road, Lagos",
  "banks":   ["9PSB"]
}

Response

Field	Type	Notes
status	string	`success` when the account was issued.
results	array	One entry per account issued.
results[].vol_reference	string	Volboo's identifier for the account.
results[].account_name	string	Name the account is held in.
results[].account_number	string	The number your customer pays into.
results[].bank_name	string	Partner bank holding the account.
results[].status	string	State of the account.
request_ref	string	Identifier for this request, worth logging.

200 Success

{
  "status": "success",
  "results": [
    {
      "vol_reference":  "VOL-695E0C5DA6A9A",
      "account_name":   "AMANDA ELUMELU",
      "account_number": "9060132960",
      "bank_name":      "9PSB",
      "status":         "created" //created or existing. 
    }
  ],
  "request_ref": "order_10432"
}

Store vol_reference against your own customer record. It is what ties a later payment or webhook event back to the account you issued.

Errors

A rejected call answers 400 with the reason in message. See Errors for the shape.