Skip to main content

​
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": "customer",
  "customer_id": "cus_abc123",
  "customer_name": "John Doe",
  "customer_email": "john@example.com",
  "currencies": ["NGN", "USDT", "USDC"]
}

​
System Wallets

Internal wallets for fees, commissions, or reserves. 
{
  "type": "system",
  "purpose": "commission",
  "currencies": ["NGN", "USDT"]
}

​
Supported Currencies

CurrencyCodeTypeStatus
Nigerian NairaNGNFiatActive
Tether USDUSDTStablecoinActive
USD CoinUSDCStablecoinActive
Binance USDBUSDStablecoinComing Soon
Celo DollarcUSDStablecoinComing Soon

​
Wallet Operations

​
Crediting Wallets (Adding Money)

Add funds to a wallet from various sources: From Fiat 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-staging.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 between wallets instantly: 
const response = await fetch('https://api-staging.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 transfers are atomic - either both debit and credit succeed, or neither happens.

​
Balance Inquiry

Check wallet balance in real-time: 
const response = await fetch('https://api-staging.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-staging.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

OperationLimit
Wallets per businessUnlimited
Currencies per wallet10
Minimum balance₦0 (or equivalent)
Maximum balance₦100,000,000 (or equivalent)
Daily transaction limit₦50,000,000 (or equivalent)
Transactions per second100

​
Best Practices

Always provide unique references to prevent duplicate transactions:
const reference = `txn_${Date.now()}_${userId}`;
Verify sufficient balance before attempting to debit:
const response = await fetch(`https://api-staging.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
}
Always store transaction IDs returned by FossaPay for reconciliation and support.
Listen to wallet webhooks for real-time updates:
  • transfer.completed
  • withdrawal.completed

​
Common Use Cases

​
Neobank Wallet

// Create fiat wallet when user signs up
curl -X POST https://api-staging.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

// User sends money to another user
const response = await fetch('https://api-staging.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 Fiat Wallet

Create your first wallet via API

Collections

Accept payments into wallets

Payouts

Withdraw from wallets to bank accounts

Webhooks

Listen to wallet events