Skip to main content
Use this endpoint to assign a dedicated, permanent payment account to one of your end-customers. Unlike dynamic virtual accounts, a customer account is not recycled after each payment — your customer receives a static account number they can reuse for all future transactions. The system verifies the customer’s identity against the core banking system using their BVN or NIN before provisioning the account. Endpoint 
POST https://baasapi.payrepmfb.com/api/v1/account/api/create_customer_account
Sandbox 
POST https://shogun-dev.xchangeboxng.com/api/v1/account/api/create_customer_account

​
Authentication

Include your Bearer token in the Authorization header: 
Authorization: Bearer <access_token>
Obtain a token from Generate Token.

​
Request body

You must supply at least one of bvn or nin. If neither is present, the request will be rejected. Both fields are accepted simultaneously when available.
​
email
string
required
The sub-customer’s email address — used for identity records and notifications.
​
phone
string
required
The sub-customer’s phone number in local format, for example "08012345678".
​
bvn
string
The sub-customer’s Bank Verification Number. Must be exactly 11 digits. Required if nin is not provided.
​
nin
string
The sub-customer’s National Identification Number. Must be exactly 11 digits. Required if bvn is not provided.
​
account_name
string
A display name for the account — typically the customer’s full name. If omitted, the system derives the name from the BVN or NIN identity record.
​
metadata
object
An arbitrary JSON object you can use to store your own reference data alongside the account, for example an internal customer ID or order reference. This field is not used by Shogun for processing.

​
Example request — with BVN

curl --request POST \
  --url https://baasapi.payrepmfb.com/api/v1/account/api/create_customer_account \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "customer@example.com",
    "phone": "08012345678",
    "bvn": "12345678901",
    "account_name": "John Doe",
    "metadata": {
      "internal_customer_id": "CUST-001"
    }
  }'

​
Example request — with NIN

curl --request POST \
  --url https://baasapi.payrepmfb.com/api/v1/account/api/create_customer_account \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "customer@example.com",
    "phone": "08012345678",
    "nin": "98765432101",
    "account_name": "Jane Doe"
  }'

​
Response

​
Success

{
  "status": true,
  "response_code": "00",
  "message": "Customer account created successfully",
  "data": {
    "account_number": "8801234567",
    "account_name": "John Doe",
    "account_type": "virtual",
    "status": "active",
    "balance": "0.000000000",
    "last_balance_update": null
  }
}
​
data.account_number
string
The permanent account number for this customer. Share it with your customer as their payment address — it remains valid indefinitely.
​
data.account_name
string
The account holder’s name as resolved from the BVN or NIN record.
​
data.account_type
string
Always "virtual" for customer accounts.
​
data.status
string
"active" — the account is ready to receive funds immediately.
​
data.balance
string
Current balance in NGN.
​
data.last_balance_update
string | null
ISO 8601 timestamp of the most recent balance change, or null if no transactions have occurred yet.

​
Error — missing identity

{
  "status": false,
  "response_code": "02",
  "message": "Either BVN or NIN must be provided.",
  "data": null
}

​
Error — provider rejected

{
  "status": false,
  "response_code": "83",
  "message": "Identity verification failed. Please check the BVN/NIN provided.",
  "data": null
}

​
Error codes

CodeMeaning
00Success
41Customer not found — your API credentials are invalid
80Service unavailable — the core banking provider is temporarily down
83Provider error — identity verification failed or the account creation request was rejected