DocumentationRecipesAPI ReferencesSupportBlog
Documentation

Settlements

Understanding how to manage settlements.

Suggest Edits

📘

Settlements are supported for all payment methods.

Your transactions are incomplete until you receive the actual funds for your payments, this is called a settlement.

Typically, after collecting payments from a customer using their preferred payment methods, you'd receive the funds in your settlement account after a holding period. This varies based on the kind of payment made.

Before receiving your settlements, you can view them as the collection balance on your dashboard. Processed settlements are sent either to your bank account or your wallet (payout balance).

Successful transactions can either be settled successfully or flagged:

  1. For successful settlements, transaction funds are settled to your bank account (settlement account) or your F4B wallet.
  2. Flagged settlements are not released to the merchant. View the settlement details to understand why it was flagged and report the flagged settlement to our support team.

Requirements

  1. Ensure that your account is approved for live transactions – Only approved accounts are eligible for settlements. Complete your KYC process to secure account approval.
  2. Add your preferred bank account details for settlements in the settings section on your dashboard.
    Configure your preferred settlement destination – choose between your F4B wallet or bank account.
  3. Your settlement should exceed the minimum settlement threshold. If the cumulative value of your transactions is lower than this threshold, We'd batch your settlement leading to a slightly longer settlement time.

Managing your Settlements

Flutterwave allows you to access relevant settlement information on your account. You can query the settlement's endpoint or get the information directly on your dashboard. You can also download the list of the transactions that make up the settlement.

This information includes:

  1. The settlement status
  2. The settlement destination
  3. Time the payment was settled
  4. Settlement type i.e. local or International

When you query the settlement endpoint, specify filters to retrieve precise settlement information. We support filtering by page number (page), start date (from), end date (to), and subaccount_id.

# Sample Request
curl --location 'https://api.flutterwave.com/v3/settlements' 
--header 'Authorization: Bearer YOUR_SECRET_KEY'

To retrieve the details of a specific settlement, include the settlement ID in your request.

# Sample Request 
curl --location 'https://api.flutterwave.com/v3/settlements/4982499' 
--header 'Authorization: Bearer YOUR_SECRET_KEY'

# Sample Response
{
    "status": "success",
    "message": "Settlement fetched",
    "data": {
        "id": 4982499,
        "account_id": 1834035,
        "merchant_name": "Adekunle Odujoko",
        "merchant_email": "[email protected]",
        "settlement_account": null,
        "bank_code": null,
        "transaction_date": "2024-06-26T01:00:00.000Z",
        "due_date": "2024-06-27T00:00:00.000Z",
        "processed_date": "2024-06-27T06:40:24.000Z",
        "status": "completed",
        "is_local": true,
        "currency": "NGN",
        "gross_amount": 200,
        "app_fee": 2.8,
        "merchant_fee": 0,
        "chargeback": 0,
        "refund": 0,
        "stampduty_charge": 0,
        "net_amount": 197.2,
        "transaction_count": 2,
        "processor_ref": "CC-SMT-469193240627064023",
        "disburse_ref": "CC-SMT-469193240627064023",
        "disburse_message": "Transfer was successful",
        "channel": "web",
        "destination": "wallet",
        "fx_data": "false",
        "flag_message": null,
        "meta": "[1402738209,1402749884]",
        "refund_meta": "[]",
        "chargeback_meta": "[]",
        "source_bankcode": null,
        "created_at": "2024-06-27T01:23:40.000Z",
        "transactions": [
            {
                "customer_email": "[email protected]",
                "flw_ref": "000015240626163808112035012551",
                "tx_ref": "Test_0007770017709",
                "id": 1444749988,
                "charged_amount": 100,
                "app_fee": 1.4,
                "merchant_fee": 0,
                "stampduty_charge": 0,
                "settlement_amount": 98.6,
                "status": "successful",
                "payment_entity": "bank_transfer",
                "transaction_date": "2024-06-26",
                "currency": "NGN",
                "card_locale": "LOCAL",
                "rrn": "N/A",
                "subaccount_settlement": 0
            },
            {
                "customer_email": "[email protected]",
                "flw_ref": "000015240626165204915842005443",
                "tx_ref": "Test_0007770017709",
                "id": 1444761926,
                "charged_amount": 100,
                "app_fee": 1.4,
                "merchant_fee": 0,
                "stampduty_charge": 0,
                "settlement_amount": 98.6,
                "status": "successful",
                "payment_entity": "bank_transfer",
                "transaction_date": "2024-06-26",
                "currency": "NGN",
                "card_locale": "LOCAL",
                "rrn": "N/A",
                "subaccount_settlement": 0
            }
        ]
    }
}

Merchants can also download this detailed settlement breakdown from their dashboards. Check here for a guide.

Updated about 1 month ago