Create a Dedicated Virtual Bank Account for Customer

Provision a dedicated virtual bank account for a customer. Once created, the account can receive bank transfers that are automatically reconciled to your merchant wallet. Each account is tied to a unique account_reference you define.

POST https://sandbox.lyseis-pay.com/virtual-accounts

Replace sandbox.lyseis-pay.com with live.lyseis-pay.com when moving to production.

Headers

Header	Value
`X-Key-Id`	Your merchant key ID
`X-Timestamp`	Unix timestamp of the request (seconds)
`X-Signature`	HMAC-SHA256 signature of the payload
`Content-Type`	`application/json`

Request Body

string

required

A unique identifier you assign to this virtual account (e.g. a customer ID or wallet ID). Must be unique across your merchant account. Used to look up the account later.

string

required

The full legal name of the customer this account is provisioned for. This name is associated with the bank account.

string

required

The customer’s email address. Used for notifications and account lookup.

string

required

ISO 4217 three-letter currency code for the account. Example: NGN.

string

required

The customer’s Bank Verification Number (BVN) — an 11-digit identifier issued by the Central Bank of Nigeria. Required for regulatory compliance when provisioning NGN accounts.

object

Optional arbitrary key-value pairs to attach to this virtual account record. Returned on subsequent lookups and webhook notifications.

{ "customer_id": "123", "plan": "premium" }

Example Request

{
  "account_reference": "customer_123",
  "customer_name": "Ada Lovelace",
  "customer_email": "ada@example.com",
  "currency_code": "NGN",
  "bvn": "22222222222",
  "metadata": { "customer_id": "123" }
}

Response

string

Indicates whether the account was successfully provisioned. A value of "success" means the virtual account is active and ready to receive funds.

string

The virtual bank account number assigned to this customer. Share this with the customer for inbound transfers.

string

The name of the partner bank or institution that issued the virtual account, e.g. "Wema Bank".

string

The CBN-assigned sort code or bank code for the issuing bank.

string

The unique reference you provided at creation. Use this to retrieve or identify the account later.

string

Paylink’s internal reference for the account reservation. Use this when contacting support about a specific virtual account.

string

The activation status of the virtual account, e.g. "active".

string

The customer name associated with the account, echoed from the request.

string

The customer email associated with the account, echoed from the request.

Example Response

{
  "status": "success",
  "account_number": "0123456789",
  "bank_name": "Wema Bank",
  "bank_code": "035",
  "account_reference": "customer_123",
  "reservation_reference": "va_res_abc123xyz",
  "account_status": "active",
  "customer_name": "Ada Lovelace",
  "customer_email": "ada@example.com"
}

Virtual account numbers are persistent — the same account number is reused for all subsequent transfers from the customer. Funds received are automatically posted to your merchant wallet and trigger a webhook if one is configured.

Payments

Virtual Accounts

Direct Debits

Refunds

Transfers

Banks

Create a Dedicated Virtual Bank Account for Customer

Headers

Request Body

Example Request

Response

Example Response

​Headers

​Request Body

​Example Request

​Response

​Example Response

Headers

Request Body

Example Request

Response

Example Response