Create Dedicated Virtual Account
Create a reserved NGN virtual account for a customer. You can either provide an existing SaySwitch customer code or create the customer and virtual account together in one request.
The customer and account remain available for future payments. If you prefer to register the customer separately, see Create Customer.
This request uses your secret key and must be made from a secure backend. Never expose a secret key in frontend or mobile-app code.
API Endpoint
POST https://backendapi.sayswitchgroup.com/api/v1/dedicated_virtual_accountAuthentication and Environments
Include these headers:
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json- Test keys beginning with
sk_test_generate simulated accounts. - Live keys beginning with
sk_live_use live account providers. - The selected customer, wallet, and account must belong to the same authenticated business and test/live environment.
Supported Customer Formats
Use an Existing Customer
Provide the customer’s customer_code:
{
"customer": "CUS_existing_code"
}When customer contains a nonempty value, SaySwitch uses that customer. An invalid code returns an error and does not fall back to automatic customer creation. The existing customer must already have first_name and last_name.
Create or Reuse a Customer Automatically
Omit customer, or send it as null or an empty string, and provide customer details:
{
"email": "john@example.com",
"first_name": "John",
"last_name": "Doe",
"phone": "08012345678",
"bvn": "12345678901",
"metadata": {
"external_customer_id": "customer-123"
}
}SaySwitch searches for a customer with the same email within the authenticated business and environment. If a match exists, that customer is reused. Supplied names, phone, and BVN fill only missing fields; existing values and metadata are preserved. The virtual account name comes from the resolved customer’s stored first and last names.
If account generation fails after a new customer is created, the customer is retained. A later request with the same email reuses that customer.
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
customer | string or null | Conditional | Existing customer_code. If nonempty, the inline customer fields are not used as a fallback. |
email | string | Without customer | Valid email address, maximum 255 characters. |
first_name | string | Without customer | Customer’s first name, maximum 255 characters. |
last_name | string | Without customer | Customer’s last name, maximum 255 characters. |
phone | string | No | Customer’s phone number, maximum 32 characters. |
bvn | string | No | An 11-digit BVN. It is optional at endpoint validation, but some live providers require it. Always send it as a string. |
metadata | object, array, or JSON string | No | Your additional customer information. Existing customer metadata is preserved when a customer is reused. |
reference | string | No | Your account reference. SaySwitch generates one when omitted. It does not replace the reference of an existing account. |
wallet_code | string | Conditional | Required when multiple NGN wallets are enabled. This endpoint accepts wallet_code, not wallet_id. |
Wallet Selection
Wallet selection depends on whether Multiple NGN Wallets is enabled for your business.
| Configuration | Rule |
|---|---|
| Multiple NGN wallets disabled | Omit wallet_code. SaySwitch selects the active default NGN wallet, or the oldest active NGN wallet when no default is marked. Supplying a code does not override this selection. |
| Multiple NGN wallets enabled | wallet_code is required for both customer formats. |
The selected wallet must be active, use NGN, belong to the authenticated merchant, and match the test/live environment. Use this same endpoint for both configurations; there is no separate wallet URL for dedicated accounts.
Request Examples
Replace the sample customer, wallet, and reference values with values from your application.
Use this when multiple NGN wallets are disabled.
curl -X POST https://backendapi.sayswitchgroup.com/api/v1/dedicated_virtual_account \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer": "CUS_existing_code",
"reference": "VA_customer_123"
}'Success Response
Both customer formats return HTTP 200. Clearly illustrative values are shown below:
{
"success": true,
"message": "NUBAN successfully created",
"data": {
"bank": {
"name": "Example Bank",
"id": 1,
"bank_code": "999",
"prefix": "EXAMPLE"
},
"account_name": "John Doe",
"account_number": "1234567890",
"currency": "NGN",
"status": "active",
"domain": "live",
"reference": "VA_customer_123",
"assignment": "reserved",
"wallet_id": 123,
"id": 456,
"created_at": "2026-11-11T00:00:00.000000Z",
"updated_at": "2026-11-11T00:00:00.000000Z",
"customer": {
"id": 789,
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"customer_code": "CUS_example",
"phone": "08012345678"
}
}
}The same success message is returned when an existing reserved account is reused. Retain data.customer.customer_code for later customer operations.
Account Reuse and Safe Retries
- A customer can have one reserved account per business and environment.
- Repeating a request for the same customer and selected wallet returns the existing account with HTTP
200. - Selecting a different wallet for a customer who already has an account returns HTTP
409; the account is not moved. - A supplied
referencedoes not replace an existing account’s reference. - If generation fails after inline customer creation, retrying with the same email reuses the retained customer.
- The reserved account remains available for subsequent payments.
HTTP Errors
These are the status codes returned by this endpoint:
| HTTP status | Meaning |
|---|---|
400 | The request is invalid or incomplete. |
401 | The customer code is invalid, the stored customer has no first or last name, merchant authorization is invalid, or a provider-specific generation error occurred. |
403 | The merchant or user is restricted or blocked. |
404 | The business or an eligible wallet could not be found. |
409 | The customer’s existing reserved account is linked to a different wallet. The account is not moved. |
422 | Multiple NGN wallets are enabled, but wallet_code was omitted. |
503 | There is no active default provider, or account generation could not complete after allocation retries. |
Use the returned HTTP status and message to decide whether to correct the request, select the correct wallet, or retry later. Do not replace these endpoint-specific statuses with more conventional alternatives in your integration.