Skip to main content

​
What is Settlement?

Settlement is the process of transferring collected funds from virtual accounts and other payment channels to your designated bank account or wallet. Fossapay offers flexible settlement options to match your business needs.
Choose between instant settlement for immediate access to funds or scheduled settlement for better cash flow management.

​
Settlement Types

​
Instant Settlement

Funds are automatically transferred to your balance immediately when a payment is received. Benefits:
  • Immediate access to funds
  • Real-time liquidity
  • No waiting period
  • Better for high-volume businesses
How it works:

​
Scheduled Settlement

Funds are batched and settled at predetermined intervals (daily, weekly, or custom). Benefits:
  • Predictable cash flow
  • Reduced transaction fees
  • Easier bulk reconciliation
  • Float management
Available Schedules:
  • T+0 - Same day settlement (default: 6 PM daily)
  • T+1 - Next business day
  • Weekly - Every Friday
  • Custom - Define your own schedule

​
Manual Settlement

You control when settlements occur through the dashboard or API. Use cases:
  • Reserve management
  • Liquidity planning
  • Complex reconciliation needs

​
Settlement Configuration

​
Setting Up Instant Settlement

await fossapay.settings.updateSettlement({
  type: 'instant',
  destination: {
    type: 'wallet', // or 'bank_account'
    wallet_id: 'wal_main_001'
  },
  currencies: ['NGN', 'USDT']
});

​
Setting Up Scheduled Settlement

await fossapay.settings.updateSettlement({
  type: 'scheduled',
  schedule: 'daily',
  settlement_time: '18:00', // 6 PM WAT
  destination: {
    type: 'bank_account',
    account_number: '0123456789',
    bank_code: '058',
    account_name: 'Acme Corporation'
  },
  minimum_amount: 10000 // Only settle if balance >= ₦10,000
});

​
Settlement Destinations

​
Wallet Settlement

Settle funds to your Fossapay wallet for instant access. 
{
  "destination": {
    "type": "wallet",
    "wallet_id": "wal_main_001"
  }
}
Advantages:
  • Instant availability
  • Use for payouts without withdrawal
  • Multi-currency support
  • No settlement fees

​
Bank Account Settlement

Settle funds directly to your bank account. 
{
  "destination": {
    "type": "bank_account",
    "account_number": "0123456789",
    "bank_code": "058",
    "account_name": "Acme Corporation"
  }
}
Advantages:
  • Direct access to funds
  • Traditional banking integration
  • Simpler accounting

​
Split Settlement

Distribute funds across multiple destinations automatically. 
{
  "destination": {
    "type": "split",
    "splits": [
      {
        "type": "wallet",
        "wallet_id": "wal_operating",
        "percentage": 80
      },
      {
        "type": "wallet",
        "wallet_id": "wal_reserve",
        "percentage": 20
      }
    ]
  }
}

​
Settlement Fees

Settlement TypeFee
Instant to WalletFree
Scheduled to WalletFree
Instant to Bank Account₦50 per transaction
Scheduled to Bank Account₦25 per batch
Manual Settlement₦50 per transaction
Fees are deducted from the settlement amount automatically.

​
Settlement Limits

ParameterLimit
Minimum settlement₦100
Maximum per transaction₦5,000,000
Daily settlement limit₦50,000,000
Settlements per dayUnlimited
Limits may vary based on your business verification level. Contact support for higher limits.

​
Reconciliation

​
Settlement Reports

Access detailed settlement reports via the dashboard or API: 
const report = await fossapay.settlements.getReport({
  start_date: '2024-01-01',
  end_date: '2024-01-31',
  format: 'json' // or 'csv', 'pdf'
});
Report Contents: 
{
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "summary": {
    "total_collections": 5000000,
    "total_fees": 12500,
    "total_settled": 4987500,
    "transaction_count": 250
  },
  "settlements": [
    {
      "settlement_id": "stl_abc123",
      "amount": 500000,
      "fee": 50,
      "net_amount": 499950,
      "destination": "0123456789",
      "status": "completed",
      "settled_at": "2024-01-15T18:00:00Z",
      "transactions": [
        {
          "transaction_id": "txn_001",
          "amount": 50000,
          "customer": "John Doe",
          "reference": "ref_001",
          "received_at": "2024-01-15T10:30:00Z"
        }
      ]
    }
  ]
}

​
Transaction Matching

Match settlements to original transactions: 
const settlement = await fossapay.settlements.get('stl_abc123');

// Get all transactions in this settlement
const transactions = await fossapay.settlements.getTransactions({
  settlement_id: 'stl_abc123'
});

​
Reconciliation Best Practices

Reconcile settlements daily even if you use scheduled settlement:
// Run daily reconciliation
const today = new Date();
const report = await fossapay.settlements.getReport({
  start_date: today.toISOString(),
  end_date: today.toISOString()
});

// Match with your internal records
await matchTransactions(report);
Listen to settlement webhooks for automatic reconciliation:
app.post('/webhooks/fossapay', (req, res) => {
  const { event, data } = req.body;

  if (event === 'settlement.completed') {
    // Trigger reconciliation
    reconcileSettlement(data.settlement_id);
  }
});
Always store settlement IDs alongside transaction records:
UPDATE transactions
SET settlement_id = 'stl_abc123',
    settled_at = '2024-01-15 18:00:00'
WHERE transaction_id IN (SELECT transaction_id FROM settlement_transactions);
Monitor failed settlements and resolve issues promptly:
const failed = await fossapay.settlements.list({
  status: 'failed',
  start_date: last7Days
});

for (const settlement of failed.data) {
  await investigateFailure(settlement);
}

​
Settlement Status

Settlements go through these statuses:
StatusDescription
pendingSettlement initiated but not processed
processingBeing processed by bank
completedSuccessfully settled
failedSettlement failed (funds returned)
reversedSettlement reversed after completion

​
Checking Settlement Status

const settlement = await fossapay.settlements.get('stl_abc123');

console.log(settlement.status);
// "completed"

​
Webhook Events

// Settlement webhook events
{
  "event": "settlement.pending",
  "data": {
    "settlement_id": "stl_abc123",
    "amount": 500000,
    "destination": "0123456789"
  }
}

{
  "event": "settlement.completed",
  "data": {
    "settlement_id": "stl_abc123",
    "amount": 500000,
    "completed_at": "2024-01-15T18:05:23Z"
  }
}

{
  "event": "settlement.failed",
  "data": {
    "settlement_id": "stl_abc123",
    "amount": 500000,
    "reason": "Invalid account number"
  }
}

​
Reserve Management

Set aside a percentage of collections as reserves: 
await fossapay.settings.updateReserve({
  enabled: true,
  percentage: 10, // Hold 10% of collections
  wallet_id: 'wal_reserve_001',
  release_schedule: 'monthly' // Release reserves monthly
});
Use cases:
  • Chargeback protection
  • Refund reserves
  • Compliance requirements
  • Cash flow management

​
Failed Settlements

Handle failed settlements gracefully: 
// Listen for failed settlement webhook
app.post('/webhooks/fossapay', (req, res) => {
  const { event, data } = req.body;

  if (event === 'settlement.failed') {
    // Log failure
    logger.error('Settlement failed', {
      settlement_id: data.settlement_id,
      reason: data.reason
    });

    // Update destination and retry
    await fossapay.settlements.retry(data.settlement_id, {
      destination: {
        type: 'bank_account',
        account_number: 'backup_account'
      }
    });
  }
});

​
Manual Settlement Triggers

Trigger settlements manually when needed: 
// Settle all pending collections
const settlement = await fossapay.settlements.create({
  amount: 'all', // or specific amount
  destination: {
    type: 'bank_account',
    account_number: '0123456789',
    bank_code: '058'
  },
  narration: 'Manual settlement - January 2024'
});

​
Settlement Calendar

Non-settlement days:
  • Saturdays and Sundays
  • Nigerian public holidays
  • Bank holidays
Scheduled settlements queued on non-settlement days will be processed on the next business day.

​
Next Steps

Configure Settlement

Set up your settlement preferences

Reconciliation Guide

Learn best practices for reconciliation

Webhooks

Handle settlement events

View Settlements

Access settlement history