Settlements
Understanding how to manage settlements.
A transaction is not considered complete until the funds are delivered to your account. This process is called settlement.
After a customer makes a payment using their preferred method, Flutterwave holds the funds for a short period before settling them into your account. The settlement timeline varies by payment method.
Before settlement is completed, the collected funds appear as your collection balance on the dashboard. Once settled, funds are transferred to either:
- Your linked bank account, or
- Your Flutterwave for Business (F4B) wallet (payout balance).
Settlements are supported for all payment methods.
Successful transactions can either be settled successfully or flagged:
- Successful Settlements: Funds are settled to your bank account or wallet as expected.
- Flagged Settlements: Funds are withheld due to compliance or other issues. You can view the settlement details to understand the reason, and should contact Flutterwave Support for assistance.
Live Transactions Only
Only transactions made in live/production mode are eligible for settlement. Ensure that your account has been approved for settlement.
Requirements
- Add your Preferred Settlement Account: Provide your bank account details or configure your F4B wallet in the dashboard settings.
- Meet the Minimum Settlement Threshold: Settlements are processed once your cumulative balance exceeds the minimum threshold. If your balance is below this amount, Flutterwave will batch your funds, which may result in delayed settlement.
Managing your Settlements
You can access and manage all settlement data in two ways:
- Dashboard: View your settlement history, current balances, and associated transactions.
- API: Use the list settlement endpoint to programmatically retrieve settlement details.
A settlement report contains a list of transactions and other details such as:
status: The current status of the settlement (e.g., SUCCESSFUL, PENDING).destination: Where the funds were sent (e.g., bank account or F4B wallet).- Settlement Timestamp: The exact time the settlement was processed.
type: Indicates whether the settlement was local or international.
Reconciling Settlements
Settlement reconciliation allows you to track payments, maintain accurate financial records, and resolve any discrepancies. It provides greater financial visibility and control over your transaction flows.
To retrieve settlement data, query the list settlements endpoint.
Use the following filters to narrow down your results:
page: Page number of the results.from: Start date for the settlement query.to: End date for the settlement query.size: Number of records to return per page.
curl --request GET \
--url 'https://api.flutterwave.cloud/developersandbox/settlements?page=1&size=10' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
You'll get a response similar to this:
{
"status": "success",
"message": "Settlements fetched",
"meta": {
"page_info": {
"total": 10,
"current_page": 1,
"total_pages": 1
}
},
"data": [
{
"id": "stm_xpNivHNWmP",
"net_amount": 150,
"gross_amount": 150,
"currency": "USD",
"meta": {},
"status": "completed",
"due_datetime": "2024-12-25T22:00:00.011Z",
"fees": [
{
"type": "stamp_duty",
"amount": 0
},
{
"type": "charge_fee",
"amount": 0
}
],
"destination": "wallet",
"charge_count": "1",
"created_datetime": "2024-12-25T22:00:00.011Z"
},
{
"id": "stm_xURpuClRd5",
"net_amount": 200,
"gross_amount": 200,
"currency": "NGN",
"meta": {},
"status": "completed",
"due_datetime": "2024-12-27T09:00:00.025Z",
"fees": [
{
"type": "stamp_duty",
"amount": 0
},
{
"type": "charge_fee",
"amount": 0
}
],
"destination": "wallet",
"charge_count": "1",
"created_datetime": "2024-12-27T09:00:00.025Z"
},
{
"id": "stm_lRP73jTEUD",
"net_amount": 150,
"gross_amount": 150,
"currency": "NGN",
"meta": {},
"status": "completed",
"due_datetime": "2025-01-21T16:00:00.010Z",
"fees": [
{
"type": "stamp_duty",
"amount": 0
},
{
"type": "charge_fee",
"amount": 0
}
],
"destination": "wallet",
"charge_count": "1",
"created_datetime": "2025-01-21T16:00:00.010Z"
},
{
"id": "stm_e80g4BVER5",
"net_amount": 150,
"gross_amount": 150,
"currency": "NGN",
"meta": {},
"status": "completed",
"due_datetime": "2025-01-21T20:00:00.196Z",
"fees": [
{
"type": "stamp_duty",
"amount": 0
},
{
"type": "charge_fee",
"amount": 0
}
],
"destination": "wallet",
"charge_count": "1",
"created_datetime": "2025-01-21T20:00:00.196Z"
},
{
"id": "stm_HFk2sqcM1c",
"net_amount": 200,
"gross_amount": 200,
"currency": "NGN",
"meta": {},
"status": "completed",
"due_datetime": "2025-01-31T11:00:00.020Z",
"fees": [
{
"type": "stamp_duty",
"amount": 0
},
{
"type": "charge_fee",
"amount": 0
}
],
"destination": "wallet",
"charge_count": "1",
"created_datetime": "2025-01-31T11:00:00.020Z"
},
{
"id": "stm_YQkhQsAZnQ",
"net_amount": 150,
"gross_amount": 150,
"currency": "USD",
"meta": {},
"status": "completed",
"due_datetime": "2025-01-31T11:00:00.048Z",
"fees": [
{
"type": "stamp_duty",
"amount": 0
},
{
"type": "charge_fee",
"amount": 0
}
],
"destination": "wallet",
"charge_count": "1",
"created_datetime": "2025-01-31T11:00:00.048Z"
},
{
"id": "stm_Wk38LvV5Hz",
"net_amount": 150,
"gross_amount": 150,
"currency": "NGN",
"meta": {},
"status": "completed",
"due_datetime": "2025-02-05T15:00:00.022Z",
"fees": [
{
"type": "stamp_duty",
"amount": 0
},
{
"type": "charge_fee",
"amount": 0
}
],
"destination": "wallet",
"charge_count": "1",
"created_datetime": "2025-02-05T15:00:00.022Z"
},
{
"id": "stm_TIrjYoJE8V",
"net_amount": 300,
"gross_amount": 300,
"currency": "NGN",
"meta": {},
"status": "completed",
"due_datetime": "2025-02-07T10:00:00.034Z",
"fees": [
{
"type": "stamp_duty",
"amount": 0
},
{
"type": "charge_fee",
"amount": 0
}
],
"destination": "wallet",
"charge_count": "2",
"created_datetime": "2025-02-07T10:00:00.034Z"
},
{
"id": "stm_tsjRlAMkoN",
"net_amount": 2000,
"gross_amount": 2000,
"currency": "NGN",
"meta": {},
"status": "completed",
"due_datetime": "2025-02-07T11:00:00.137Z",
"fees": [
{
"type": "stamp_duty",
"amount": 0
},
{
"type": "charge_fee",
"amount": 0
}
],
"destination": "wallet",
"charge_count": "1",
"created_datetime": "2025-02-07T11:00:00.137Z"
},
{
"id": "stm_JJo3vjtffW",
"net_amount": 2000,
"gross_amount": 2000,
"currency": "NGN",
"meta": {},
"status": "completed",
"due_datetime": "2025-02-07T12:00:00.022Z",
"fees": [
{
"type": "stamp_duty",
"amount": 0
},
{
"type": "charge_fee",
"amount": 0
}
],
"destination": "wallet",
"charge_count": "1",
"created_datetime": "2025-02-07T12:00:00.022Z"
}
]
}
To retrieve the details of a specific settlement, include the settlement ID in your request.
curl --request GET \
--url 'https://api.flutterwave.cloud/developersandbox/settlements/id' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
You'll get a response similar to this:
{
"status": "success",
"message": "Settlement fetched",
"data": {
"id": "stm_xpNivHNWmP",
"net_amount": 150,
"gross_amount": 150,
"currency": "USD",
"meta": {},
"status": "completed",
"due_datetime": "2024-12-25T22:00:00.011Z",
"fees": [
{
"type": "stamp_duty",
"amount": 0
},
{
"type": "charge_fee",
"amount": 0
}
],
"destination": "wallet",
"charge_count": "1",
"charges": [],
"created_datetime": "2024-12-25T22:00:00.011Z"
},
"meta": {
"page_info": {
"total": 1,
"current_page": 1,
"total_pages": 0
}
}
}
Updated about 23 hours ago