Skip to main content

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

Headers

NameTypeRequiredDescription
AuthorizationstringRequiredBearer token with your secret API key
Content-TypestringRequiredMust be application/json
Idempotency-KeystringRecommendedUnique key to prevent duplicate wallet creation

Request Body

customer_id
string
required
Unique identifier for the customer who will own this wallet
One customer can have multiple wallets in different currencies
currency
string
default:"NGN"
Primary currency for the walletSupported currencies: NGN, USD, GBP, EUR, GHS, KES, ZAR
wallet_type
string
default:"personal"
Type of wallet to createAvailable types:
  • personal - Individual customer wallet
  • business - Business/corporate wallet
  • savings - High-yield savings wallet
  • current - Current account wallet
label
string
Human-readable label for the wallet (e.g., “Main Account”, “Savings”, “Business Funds”)
customer_info
object
required
Customer information for wallet creation
initial_deposit
string
default:"0"
Initial deposit amount in the smallest currency unit (optional)
Initial deposits require sufficient balance in your main account
features
object
Wallet features configuration
limits
object
Transaction limits for the wallet
metadata
object
Additional information about the wallet
{
  "source": "mobile_app",
  "referral_code": "REF123",
  "customer_segment": "premium",
  "created_by": "customer_service"
}

Example Request

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

status
string
Request status indicator - "success" or "error"
message
string
Human-readable message describing the result
data
object
Created wallet data object

Example Response

{
  "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

Individual Customer AccountsFeatures:
  • 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

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

// 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;
};

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

1

Creation

Create wallet with appropriate type and features based on customer profile
2

Activation

Activate wallet after successful creation and initial verification
3

Monitoring

Monitor wallet activities, balances, and compliance status
4

Maintenance

Regular limit reviews, feature updates, and compliance checks
5

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.