> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fossapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallets

> Multi-currency wallet infrastructure for your fintech

## 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.

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

## Key Features

<CardGroup cols={2}>
  <Card color="#0080FF" title="Multi-Currency Support" icon="coins">
    Hold balances in NGN, USDT, USDC, and other stablecoins
  </Card>

  <Card color="#0080FF" title="Instant Transfers" icon="bolt">
    Move money between wallets in milliseconds
  </Card>

  <Card color="#0080FF" title="Real-time Balance" icon="gauge">
    Query balances and transaction history instantly
  </Card>

  <Card color="#0080FF" title="Double-Entry Ledger" icon="book">
    Bank-grade accounting with full audit trail
  </Card>
</CardGroup>

## Wallet Types

### Customer Wallets

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

```json theme={null}
{
  "type": "customer",
  "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  | Fiat       | Active      |
| Tether USD     | USDT | Stablecoin | Active      |
| USD Coin       | USDC | Stablecoin | Active      |
| Binance USD    | BUSD | Stablecoin | Coming Soon |
| Celo Dollar    | cUSD | Stablecoin | Coming Soon |

## Wallet Operations

### Crediting Wallets (Adding Money)

Add funds to a wallet from various sources:

**From Fiat Wallet Payment:**

```javascript theme={null}
// 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:**

```javascript theme={null}
// 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 between wallets instantly:

```javascript theme={null}
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();
```

<Note>
  Wallet transfers are atomic - either both debit and credit succeed, or neither happens.
</Note>

### Balance Inquiry

Check wallet balance in real-time:

```javascript theme={null}
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:

```javascript theme={null}
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:**

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Use References for Idempotency">
    Always provide unique references to prevent duplicate transactions:

    ```javascript theme={null}
    const reference = `txn_${Date.now()}_${userId}`;
    ```
  </Accordion>

  <Accordion title="Check Balance Before Debit">
    Verify sufficient balance before attempting to debit:

    ```javascript theme={null}
    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
    }
    ```
  </Accordion>

  <Accordion title="Store Transaction IDs">
    Always store transaction IDs returned by FossaPay for reconciliation and support.
  </Accordion>

  <Accordion title="Implement Webhooks">
    Listen to wallet webhooks for real-time updates:

    * `transfer.completed`
    * `withdrawal.completed`
  </Accordion>
</AccordionGroup>

## Common Use Cases

### Neobank Wallet

```javascript theme={null}
// Create fiat 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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

<CardGroup cols={2}>
  <Card color="#0080FF" title="Create Fiat Wallet" icon="code" href="/api-reference/virtual-account/create-wallet">
    Create your first wallet via API
  </Card>

  <Card color="#0080FF" title="Collections" icon="building-columns" href="/guides/collections">
    Accept payments into wallets
  </Card>

  <Card color="#0080FF" title="Payouts" icon="money-bill-transfer" href="/guides/payouts">
    Withdraw from wallets to bank accounts
  </Card>

  <Card color="#0080FF" title="Webhooks" icon="webhook" href="/concepts/webhooks">
    Listen to wallet events
  </Card>
</CardGroup>