Create a virtual account for a customer. Kyshi uses the business virtual-account provider configured for the requested currency.

-H "x-api-key: your_secret_key"

POST {{host}}/v1/wallets

Request Body

Field	Data Type	Required	Description
customer	object	Yes	Customer details. Include at least `email`; `firstName`, `lastName`, and `phoneNumber` are recommended.
currency	string	Yes	Collection currency. Supported values: `NGN`, `KES`, `ZAR`, `GHS`, `XOF`, `USD`; availability depends on your enabled integrations.
accountType	string	Yes	`INDIVIDUAL` or `COOPERATE`. Defaults to `INDIVIDUAL`.
accountCategory	string	Yes	`VIRTUAL_ACCOUNT` for a temporary account or `DEDICATED_VIRTUAL_ACCOUNT` for a reusable account. Defaults to `VIRTUAL_ACCOUNT`.
bank	string	No	Provider value. Kyshi currently resolves this from your configured provider.
amount	number	No	Expected collection amount in major currency units. For temporary accounts, Kyshi can add customer-borne fees to the payable amount.
reference	string	No	Your unique virtual account reference. If omitted, Kyshi generates one.
feeBearer	string	No	Who pays virtual-account collection fees. Allowed values: `CUSTOMER`, `MERCHANT`. Defaults to `CUSTOMER`. If `CUSTOMER`, Kyshi adds fees to the payable amount. If `MERCHANT`, the payable amount remains the requested `amount` and fees are deducted from the settled amount.
expiresAt	string	No	Expiry in minutes for temporary individual virtual accounts. Must be a numeric string between `30` and `4320` when supplied.

{
  "customer": {
    "email": "[email protected]",
    "firstName": "Ada",
    "lastName": "Okafor",
    "phoneNumber": "2348012345678"
  },
  "currency": "NGN",
  "accountType": "INDIVIDUAL",
  "accountCategory": "VIRTUAL_ACCOUNT",
  "amount": 5000,
  "reference": "ORDER-VA-10001",
  "feeBearer": "CUSTOMER",
  "expiresAt": "60"
}

Set feeBearer to MERCHANT when the payer should transfer exactly the requested amount. For example, if amount is 1000 and applicable fees are 70, the payable amount remains 1000 and Kyshi credits the merchant with 930.

{
  "status": true,
  "message": "Success",
  "code": 201,
  "data": {
    "id": "89d8f903-96f6-48df-af97-1f2b3bb64260",
    "accountNumber": "1234567890",
    "accountName": "KYSHI / ADA OKAFOR",
    "bankCode": "999999",
    "bankName": "Provider Bank",
    "balance": 5000,
    "accountCategory": "VIRTUAL_ACCOUNT",
    "accountType": "INDIVIDUAL",
    "reference": "VA_123456789",
    "expiresAt": "60",
    "isPermanent": false,
    "provider": "VFD",
    "mode": "live",
    "createdAt": "2026-05-20T10:15:00.000Z"
  }
}