Wallets

What are Wallets?

Wallets are digital accounts that hold customer balances in multiple currencies. With FossaPay’s wallet infrastructure, you can create customer wallets, hold balances in NGN and stablecoins, and manage internal ledgers seamlessly.

Wallets enable you to build neobank features like balance holding, peer-to-peer transfers, and multi-currency accounts without managing complex ledger infrastructure.

Key Features

Multi-Currency Support

Hold balances in NGN, USDT, USDC, and other stablecoins

Instant Transfers

Move money between wallets in milliseconds

Real-time Balance

Query balances and transaction history instantly

Double-Entry Ledger

Bank-grade accounting with full audit trail

Wallet Types

Customer Wallets

Individual wallets for your end users. Each wallet can hold multiple currencies.

{
  "type": "individual",
  "customer_id": "cus_abc123",
  "customer_name": "John Doe",
  "customer_email": "john@example.com",
  "currencies": ["NGN", "USDT", "USDC"]
}

Supported Currencies

Currency	Code	Type	Status
Nigerian Naira	NGN	NGN	Active
Tether USD	USDT	Stablecoin	Active
USD Coin	USDC	Stablecoin	Active

Wallet Operations

Crediting Wallets (Adding Money)

Add funds to a wallet from various sources: From NGN Wallet Payment:

// Automatic via webhook when payment is received
// Webhook handler
app.post('/webhooks/fossapay', (req, res) => {
  const { event, data } = req.body;

  if (event === 'deposit.completed') {
    // Credit the customer's wallet
    // Use the wallet ID from your database
    await creditCustomerWallet(data.customerId, data.amount);
  }
});

Debiting Wallets (Removing Money)

Remove funds from a wallet: For Payout:

// When customer requests withdrawal
// 1. Debit the wallet (conceptually)
// 2. Process inter-bank transfer

// API call to initiate transfer
curl -X POST https://api-production.fossapay.com/api/v1/transfers/fiat/inter-bank \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_123",
    "destinationBankCode": "044",
    "destinationAccountName": "Customer Name",
    "destinationAccountNumber": "0123456789",
    "destinationBankName": "ACCESS BANK",
    "reference": "withdrawal-001",
    "remarks": "Bank withdrawal",
    "amount": 25000
  }'

Wallet-to-Wallet Transfers

Transfer funds instantly and free of charge between two FossaPay customers under the same business. Both the sending and receiving account numbers must belong to FossaPay NGN wallets created under your business:

const response = await fetch('https://api-production.fossapay.com/api/v1/wallets/fiat/transfers/wallet-to-wallet', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fromAccount: '1234567890', // sender's account number
    toAccount: '0987654321',   // receiver's account number
    amount: 10000,
    reference: 'p2p-transfer-001',
    narration: 'Payment for services'
  })
});

const data = await response.json();

Wallet-to-wallet transfers are free and atomic - either both the debit and credit succeed, or neither happens. Use an inter-bank transfer when the recipient uses an external bank.

Balance Inquiry

Check wallet balance in real-time:

const response = await fetch('https://api-production.fossapay.com/api/v1/wallets/fiat/wal_xyz789', {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
const balance = data.data;

console.log(balance);
// {
//   "id": "wal_xyz789",
//   "availableBalance": "150000.00",
//   "ledgerBalance": "150000.00"
// }

Balance Types

Available Balance

Funds that can be used immediately for transactions.

Ledger Balance

Total balance including pending transactions.

Pending Balance

Funds that are in transit or on hold.

Ledger Balance = Available Balance + Pending Balance

Transaction History

Retrieve wallet transaction history:

const response = await fetch('https://api-production.fossapay.com/api/v1/wallets/fiat/wal_xyz789/transactions?startDate=2024-01-01&endDate=2024-01-31&limit=50&page=1', {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
const transactions = data.transactions;

Response:

{
  "wallet_id": "wal_xyz789",
  "currency": "NGN",
  "transactions": [
    {
      "id": "txn_001",
      "type": "credit",
      "amount": 50000,
      "balance_before": 100000,
      "balance_after": 150000,
      "narration": "Wallet top-up",
      "reference": "ref_001",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "txn_002",
      "type": "debit",
      "amount": 25000,
      "balance_before": 150000,
      "balance_after": 125000,
      "narration": "Transfer to Jane",
      "reference": "ref_002",
      "created_at": "2024-01-16T14:20:00Z"
    }
  ],
  "pagination": {
    "total": 125,
    "limit": 50,
    "offset": 0
  }
}

Wallet Limits

Operation	Limit
Wallets per business	Unlimited
Currencies per wallet	10
Minimum balance	₦0 (or equivalent)
Maximum balance	₦100,000,000 (or equivalent)
Daily transaction limit	₦50,000,000 (or equivalent)
Transactions per second	100

Best Practices

Use References for Idempotency

Always provide unique references to prevent duplicate transactions:

const reference = `txn_${Date.now()}_${userId}`;

Check Balance Before Debit

Verify sufficient balance before attempting to debit:

const response = await fetch(`https://api-production.fossapay.com/api/v1/wallets/fiat/${walletId}`, {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
const balance = data.data;

if (parseFloat(balance.availableBalance) >= amount) {
  // Proceed with debit
}

Store Transaction IDs

Always store transaction IDs returned by FossaPay for reconciliation and support.

Implement Webhooks

Listen to wallet webhooks for real-time updates:

transfer.completed
withdrawal.completed

Common Use Cases

Neobank Wallet

// Create NGN wallet when user signs up
curl -X POST https://api-production.fossapay.com/api/v1/wallets/fiat/create \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_123",
    "walletName": "Main Wallet",
    "walletReference": "wallet_'$(date +%s)'"
  }'

// The wallet account number can be used for collections

Marketplace Split Payments

// Receive payment via webhook
const payment = event.data; // from webhook

// Split payment logic (crediting is handled via webhooks or internal processes)
// Merchant receives 80%, platform receives 20%
// Wallets are credited automatically based on webhook configuration

Peer-to-Peer Transfers

This free flow applies only when both users are customers under your business and both accounts are FossaPay NGN wallets.

// User sends money to another user
const response = await fetch('https://api-production.fossapay.com/api/v1/wallets/fiat/transfers/wallet-to-wallet', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fromAccount: senderAccountNumber, // sender's account number
    toAccount: receiverAccountNumber,   // receiver's account number
    amount: 5000,
    reference: 'p2p-' + Date.now(),
    narration: 'Payment from friend'
  })
});

const data = await response.json();

Next Steps

Create NGN Wallet

Create your first wallet via API

Collections

Accept payments into wallets

Payouts

Withdraw from wallets to bank accounts

Webhooks

Listen to wallet events

Getting Started

Core Concepts

Guides

AI Tools

What are Wallets?

Key Features

Multi-Currency Support

Instant Transfers

Real-time Balance

Double-Entry Ledger

Wallet Types

Customer Wallets

Supported Currencies

Wallet Operations

Crediting Wallets (Adding Money)

Debiting Wallets (Removing Money)

Wallet-to-Wallet Transfers

Balance Inquiry

Balance Types

Available Balance

Ledger Balance

Pending Balance

Transaction History

Wallet Limits

Best Practices

Common Use Cases

Neobank Wallet

Marketplace Split Payments

Peer-to-Peer Transfers

Next Steps

Create NGN Wallet

Collections

Payouts

Webhooks

​What are Wallets?

​Key Features

Multi-Currency Support

Instant Transfers

Real-time Balance

Double-Entry Ledger

​Wallet Types

​Customer Wallets

​Supported Currencies

​Wallet Operations

​Crediting Wallets (Adding Money)

​Debiting Wallets (Removing Money)

​Wallet-to-Wallet Transfers

​Balance Inquiry

​Balance Types

​Available Balance

​Ledger Balance

​Pending Balance

​Transaction History

​Wallet Limits

​Best Practices

​Common Use Cases

​Neobank Wallet

​Marketplace Split Payments

​Peer-to-Peer Transfers

​Next Steps

Create NGN Wallet

Collections

Payouts

Webhooks

What are Wallets?

Key Features

Wallet Types

Customer Wallets

Supported Currencies

Wallet Operations

Crediting Wallets (Adding Money)

Debiting Wallets (Removing Money)

Wallet-to-Wallet Transfers

Balance Inquiry

Balance Types

Available Balance

Ledger Balance

Pending Balance

Transaction History

Wallet Limits

Best Practices

Common Use Cases

Neobank Wallet

Marketplace Split Payments

Peer-to-Peer Transfers

Next Steps