Skip to main content
POST
https://api.fossapay.com
/
v1
/
virtual-accounts
Create Virtual Account
curl --request POST \
  --url https://api.fossapay.com/v1/virtual-accounts \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "customer_name": "<string>",
  "customer_email": "<string>",
  "customer_phone": "<string>",
  "customer_id": "<string>",
  "amount": 123,
  "expires_at": "<string>",
  "account_name": "<string>",
  "metadata": {}
}
'
{
  "status": "success",
  "message": "Virtual account created successfully",
  "data": {
    "virtual_account_id": "va_abc123xyz",
    "account_number": "1234567890",
    "account_name": "FOSSAPAY - JOHN DOE",
    "bank_name": "Wema Bank",
    "bank_code": "035",
    "type": "dedicated",
    "status": "active",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "customer_phone": "+2348012345678",
    "metadata": {
      "user_id": "12345",
      "purpose": "wallet_topup"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}

​
Request

​
type
string
required
Account type: dedicated for permanent accounts, temporary for one-time payments
​
customer_name
string
required
Full name of the customer (2-100 characters)
​
customer_email
string
required
Customer’s email address
​
customer_phone
string
Customer’s phone number in international format (e.g., +2348012345678)
​
customer_id
string
Your internal customer ID for reference
​
amount
number
Expected payment amount (required for temporary accounts)
​
expires_at
string
Expiration date for temporary accounts (ISO 8601 format)
​
account_name
string
Custom account name (defaults to business name + customer name)
​
metadata
object
Custom data to store with the virtual account (max 10 keys)

​
Request Example

curl -X POST https://api.fossapay.com/v1/virtual-accounts \
  -H "Authorization: Bearer fp_live_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "dedicated",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "customer_phone": "+2348012345678",
    "customer_id": "cus_123",
    "metadata": {
      "user_id": "12345",
      "purpose": "wallet_topup"
    }
  }'

const fossapay = require('fossapay-node');
const client = new fossapay('fp_live_sk_xxxxxxxx');

const account = await client.virtualAccounts.create({
  type: 'dedicated',
  customer_name: 'John Doe',
  customer_email: '[email protected]',
  customer_phone: '+2348012345678',
  metadata: {
    user_id: '12345'
  }
});

from fossapay import Fossapay

client = Fossapay('fp_live_sk_xxxxxxxx')

account = client.virtual_accounts.create(
    type='dedicated',
    customer_name='John Doe',
    customer_email='[email protected]',
    customer_phone='+2348012345678',
    metadata={
        'user_id': '12345'
    }
)

​
Response

​
status
string
Response status: success or error
​
message
string
Human-readable response message
​
data
object

​
Response Example

{
  "status": "success",
  "message": "Virtual account created successfully",
  "data": {
    "virtual_account_id": "va_abc123xyz",
    "account_number": "1234567890",
    "account_name": "FOSSAPAY - JOHN DOE",
    "bank_name": "Wema Bank",
    "bank_code": "035",
    "type": "dedicated",
    "status": "active",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "customer_phone": "+2348012345678",
    "metadata": {
      "user_id": "12345",
      "purpose": "wallet_topup"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}

​
Error Codes

CodeDescription
INVALID_EMAILEmail address is invalid
INVALID_PHONEPhone number is invalid
CUSTOMER_NAME_TOO_SHORTCustomer name must be at least 2 characters
ACCOUNT_LIMIT_REACHEDMaximum number of virtual accounts reached
INVALID_EXPIRY_DATEExpiry date must be in the future
AMOUNT_REQUIREDAmount is required for temporary accounts
Rate Limit: 100 requests per minute
Store the virtual_account_id in your database for future reference and transaction matching.