Create Wallet
Create a digital wallet for customers to securely store funds, make payments, and receive money. PayVessel wallets support multiple currencies and provide real-time balance tracking.
Digital wallets enable you to build comprehensive fintech solutions with account-to-account transfers, bill payments, and merchant transactions.
Endpoint
POST /wallets/create
Name Type Required Description Authorizationstring Required Bearer token with your secret API key Content-Typestring Required Must be application/json Idempotency-Keystring Recommended Unique key to prevent duplicate wallet creation
Request Body
Unique identifier for the customer who will own this wallet One customer can have multiple wallets in different currencies
Primary currency for the wallet Supported currencies: NGN, USD, GBP, EUR, GHS, KES, ZAR
Type of wallet to create Available types:
personal - Individual customer wallet
business - Business/corporate wallet
savings - High-yield savings wallet
current - Current account wallet
Human-readable label for the wallet (e.g., “Main Account”, “Savings”, “Business Funds”)
Customer information for wallet creation Show Customer Info Object
Customer’s phone number in international format
customer_info.date_of_birth
Customer’s date of birth in YYYY-MM-DD format
Customer’s Bank Verification Number (required for NGN wallets)
Customer’s address information customer_info.address.street
Street address
customer_info.address.city
City
customer_info.address.state
State or province
customer_info.address.country
Country code (ISO 3166-1 alpha-2)
customer_info.address.postal_code
Postal or ZIP code
Initial deposit amount in the smallest currency unit (optional) Initial deposits require sufficient balance in your main account
Wallet features configuration Enable virtual debit card for the wallet
Allow bill payments from this wallet
Enable transfers to/from this wallet
features.savings_interest
Enable interest earning for savings wallets
Allow overdraft facility (business wallets only)
Transaction limits for the wallet limits.daily_transaction_limit
Maximum daily transaction amount in smallest currency unit
limits.monthly_transaction_limit
Maximum monthly transaction amount in smallest currency unit
limits.single_transaction_limit
Maximum single transaction amount in smallest currency unit
limits.daily_transaction_count
Maximum number of transactions per day
Additional information about the wallet {
"source" : "mobile_app" ,
"referral_code" : "REF123" ,
"customer_segment" : "premium" ,
"created_by" : "customer_service"
}
Example Request
cURL - Personal Wallet
Node.js
PHP
Python
curl -X POST https://api.payvessel.com/wallets/create \
-H "Authorization: Bearer sk_test_abc123..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: wallet_2024_001" \
-d '{
"customer_id": "CUST_12345",
"currency": "NGN",
"wallet_type": "personal",
"label": "Main Account",
"customer_info": {
"first_name": "John",
"last_name": "Doe",
"email": "[email protected] ",
"phone": "+2348012345678",
"date_of_birth": "1990-05-15",
"bvn": "12345678901",
"address": {
"street": "15 Victoria Island Road",
"city": "Lagos",
"state": "Lagos",
"country": "NG",
"postal_code": "101001"
}
},
"initial_deposit": "50000",
"features": {
"debit_card": true,
"bill_payments": true,
"transfers": true
},
"limits": {
"daily_transaction_limit": "500000",
"single_transaction_limit": "100000"
},
"metadata": {
"source": "mobile_app",
"customer_segment": "standard"
}
}'
Response
Request status indicator - "success" or "error"
Human-readable message describing the result
Created wallet data object 10-digit account number for the wallet (NGN wallets)
Account name (customer’s full name)
Virtual bank name for the wallet
Bank code for transfers to this wallet
Customer identifier who owns the wallet
Human-readable wallet label
Current wallet balance information Available balance in smallest currency unit
Ledger balance in smallest currency unit
Wallet status - "active", "inactive", "suspended", "closed"
Transaction limits configuration
Virtual debit card details (if enabled) data.virtual_card.card_id
Unique card identifier
data.virtual_card.masked_pan
Masked card number (e.g., 5399****1234)
data.virtual_card.card_type
Card brand - "mastercard", "visa"
Card status - "active", "inactive", "blocked"
ISO 8601 timestamp when wallet was created
ISO 8601 timestamp when wallet was last updated
Custom metadata attached to the wallet
Example Response
201 Created - Personal Wallet
201 Created - Business Wallet
400 Bad Request - Validation Error
409 Conflict - Duplicate Wallet
{
"status" : "success" ,
"message" : "Wallet created successfully" ,
"data" : {
"wallet_id" : "WLT_xyz789abc123456" ,
"account_number" : "1234567890" ,
"account_name" : "John Doe" ,
"bank_name" : "PayVessel Microfinance Bank" ,
"bank_code" : "50746" ,
"customer_id" : "CUST_12345" ,
"currency" : "NGN" ,
"wallet_type" : "personal" ,
"label" : "Main Account" ,
"balance" : {
"available" : "50000" ,
"ledger" : "50000" ,
"currency" : "NGN"
},
"status" : "active" ,
"features" : {
"debit_card" : true ,
"bill_payments" : true ,
"transfers" : true ,
"savings_interest" : false ,
"overdraft" : false
},
"limits" : {
"daily_transaction_limit" : "500000" ,
"monthly_transaction_limit" : "10000000" ,
"single_transaction_limit" : "100000" ,
"daily_transaction_count" : 50
},
"virtual_card" : {
"card_id" : "CRD_abc123xyz789" ,
"masked_pan" : "5399****1234" ,
"card_type" : "mastercard" ,
"status" : "active"
},
"created_at" : "2024-01-15T14:30:00Z" ,
"updated_at" : "2024-01-15T14:30:00Z" ,
"metadata" : {
"source" : "mobile_app" ,
"customer_segment" : "standard"
}
}
}
Wallet Types Guide
Personal Wallet
Business Wallet
Savings Wallet
Current Wallet
Individual Customer Accounts Features:
Single currency per wallet
Debit card issuance available
Standard transaction limits
Mobile and web access
Use cases:
Consumer banking
Digital payments
Savings accounts
Remittance receiving
Limits:
Daily: ₦500,000
Monthly: ₦10,000,000
Single transaction: ₦100,000
Corporate and SME Accounts Features:
Higher transaction limits
Overdraft facility available
Multi-user access (coming soon)
Detailed reporting
Use cases:
Business operations
Vendor payments
Payroll processing
Revenue collection
Limits:
Daily: ₦5,000,000
Monthly: ₦100,000,000
Single transaction: ₦1,000,000
Interest-Earning Accounts Features:
Interest accrual
Limited withdrawal frequency
Goal-based savings
Automatic transfers
Use cases:
Emergency funds
Goal savings
Interest earning
Long-term investments
Interest Rate:
Up to 10% per annum
Daily interest calculation
Monthly interest payment
High-Volume Transaction Accounts Features:
Unlimited transactions
No minimum balance
Overdraft facility
Premium support
Use cases:
High-frequency trading
Payment processing
Financial services
Corporate treasury
Benefits:
Zero transaction fees
Priority processing
Dedicated support
Currency Support
Primary Currency
Full banking features
Virtual account numbers
Debit card issuance
Bill payment integration
USSD access codes
Requirements:
Valid BVN
Nigerian address
Phone verification
International Currency
USD account numbers
International transfers
Card payments abroad
Forex services
Features:
SWIFT transfers
Multi-currency cards
Exchange rate protection
UK Currency Support
GBP virtual accounts
UK bank transfers
European payments
Brexit-compliant
Benefits:
Competitive exchange rates
Fast UK transfers
Regulatory compliance
Regional Support
GHS : Ghana Cedis
XOF : West African Francs
LRD : Liberian Dollars
Features:
Local payment methods
Mobile money integration
Cross-border transfers
Integration Patterns
Neobank App
Business Platform
Savings Platform
Multi-Currency Platform
// Create customer wallet during onboarding
const createCustomerWallet = async ( customerData , verificationsCompleted ) => {
// Ensure KYC is completed
if ( ! verificationsCompleted . bvn || ! verificationsCompleted . identity ) {
throw new Error ( 'KYC verification required' );
}
const wallet = await payvessel . wallets . create ({
customer_id: customerData . id ,
currency: 'NGN' ,
wallet_type: 'personal' ,
label: 'Main Account' ,
customer_info: {
first_name: customerData . first_name ,
last_name: customerData . last_name ,
email: customerData . email ,
phone: customerData . phone ,
date_of_birth: customerData . date_of_birth ,
bvn: customerData . bvn ,
address: customerData . address
},
features: {
debit_card: true ,
bill_payments: true ,
transfers: true
},
limits: {
daily_transaction_limit: customerData . tier === 'premium' ? '1000000' : '500000' ,
single_transaction_limit: '100000'
},
metadata: {
onboarding_source: 'mobile_app' ,
customer_tier: customerData . tier ,
referral_code: customerData . referral_code
}
});
// Store wallet info in your database
await saveCustomerWallet ( customerData . id , wallet . data );
// Generate virtual debit card if enabled
if ( wallet . data . virtual_card ) {
await provisionVirtualCard ( customerData . id , wallet . data . virtual_card );
}
return wallet . data ;
};
// Create business wallet with advanced features
const createBusinessWallet = async ( businessData ) => {
const wallet = await payvessel . wallets . create ({
customer_id: businessData . business_id ,
currency: 'NGN' ,
wallet_type: 'business' ,
label: ` ${ businessData . business_name } Operating Account` ,
customer_info: {
first_name: businessData . ceo_first_name ,
last_name: businessData . ceo_last_name ,
email: businessData . business_email ,
phone: businessData . business_phone ,
bvn: businessData . ceo_bvn ,
address: businessData . business_address
},
features: {
debit_card: false ,
bill_payments: true ,
transfers: true ,
overdraft: businessData . credit_approved
},
limits: {
daily_transaction_limit: businessData . daily_limit || '5000000' ,
monthly_transaction_limit: businessData . monthly_limit || '50000000' ,
single_transaction_limit: '2000000'
},
metadata: {
business_type: businessData . business_type ,
industry: businessData . industry ,
registration_number: businessData . cac_number ,
tax_id: businessData . tin
}
});
// Set up business-specific features
await setupBusinessFeatures ( businessData . business_id , wallet . data );
return wallet . data ;
};
// Create goal-based savings wallet
const createSavingsWallet = async ( customerId , savingsGoal ) => {
const wallet = await payvessel . wallets . create ({
customer_id: customerId ,
currency: 'NGN' ,
wallet_type: 'savings' ,
label: savingsGoal . name ,
customer_info: await getCustomerInfo ( customerId ),
features: {
debit_card: false ,
bill_payments: false ,
transfers: true ,
savings_interest: true
},
limits: {
daily_transaction_limit: '100000' ,
single_transaction_limit: '50000' ,
daily_transaction_count: 5
},
metadata: {
goal_amount: savingsGoal . target_amount ,
goal_date: savingsGoal . target_date ,
auto_save_amount: savingsGoal . monthly_contribution ,
goal_type: savingsGoal . category
}
});
// Set up automatic savings
if ( savingsGoal . auto_save ) {
await setupAutomaticSavings ( customerId , wallet . data . wallet_id , savingsGoal );
}
return wallet . data ;
};
// Create wallets for multiple currencies
const createMultiCurrencyWallets = async ( customerId , currencies ) => {
const wallets = [];
for ( const currency of currencies ) {
const wallet = await payvessel . wallets . create ({
customer_id: customerId ,
currency: currency ,
wallet_type: 'personal' ,
label: ` ${ currency } Account` ,
customer_info: await getCustomerInfo ( customerId ),
features: {
debit_card: currency === 'NGN' ,
bill_payments: currency === 'NGN' ,
transfers: true
},
limits: getCurrencyLimits ( currency ),
metadata: {
primary_currency: currency === 'NGN' ,
forex_enabled: true ,
cross_currency_transfers: true
}
});
wallets . push ( wallet . data );
}
// Link wallets for easy currency conversion
await linkMultiCurrencyWallets ( customerId , wallets );
return wallets ;
};
Best Practices
KYC Compliance Always complete customer verification before wallet creation, especially for NGN wallets requiring BVN
Appropriate Limits Set transaction limits based on customer risk profile and business requirements
Feature Planning Enable only necessary features initially. Additional features can be activated later
Metadata Usage Use metadata extensively for customer segmentation, reporting, and business intelligence
Error Handling Implement robust error handling for wallet creation failures and duplicate prevention
Status Monitoring Monitor wallet status and handle status changes (suspensions, closures) appropriately
Wallet Lifecycle Management
Creation
Create wallet with appropriate type and features based on customer profile
Activation
Activate wallet after successful creation and initial verification
Monitoring
Monitor wallet activities, balances, and compliance status
Maintenance
Regular limit reviews, feature updates, and compliance checks
Closure
Proper wallet closure process when requested or required
Next Steps
After creating a wallet:
Webhook Events
This endpoint triggers the following webhook events:
wallet.created - Wallet successfully created
wallet.activated - Wallet activated and ready for use
card.issued - Virtual card issued (if debit_card feature enabled)
account.opened - Virtual bank account opened (for NGN wallets)
Pro Tip : Use wallet metadata to store business-specific information like customer segments, referral sources, and feature flags for easy filtering and reporting.