Dedicated Virtual AccountsCreate Dedicated Virtual Account

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_account

Authentication 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

FieldTypeRequiredDescription
customerstring or nullConditionalExisting customer_code. If nonempty, the inline customer fields are not used as a fallback.
emailstringWithout customerValid email address, maximum 255 characters.
first_namestringWithout customerCustomer’s first name, maximum 255 characters.
last_namestringWithout customerCustomer’s last name, maximum 255 characters.
phonestringNoCustomer’s phone number, maximum 32 characters.
bvnstringNoAn 11-digit BVN. It is optional at endpoint validation, but some live providers require it. Always send it as a string.
metadataobject, array, or JSON stringNoYour additional customer information. Existing customer metadata is preserved when a customer is reused.
referencestringNoYour account reference. SaySwitch generates one when omitted. It does not replace the reference of an existing account.
wallet_codestringConditionalRequired 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.

ConfigurationRule
Multiple NGN wallets disabledOmit 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 enabledwallet_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 reference does 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 statusMeaning
400The request is invalid or incomplete.
401The customer code is invalid, the stored customer has no first or last name, merchant authorization is invalid, or a provider-specific generation error occurred.
403The merchant or user is restricted or blocked.
404The business or an eligible wallet could not be found.
409The customer’s existing reserved account is linked to a different wallet. The account is not moved.
422Multiple NGN wallets are enabled, but wallet_code was omitted.
503There 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.