Flutterwave escrow: funds wait for your settle call, they skip auto-settlement

TL;DR

Escrow and split payments are separate features that compose. With split payments alone, Flutterwave auto-settles each seller's collected funds on the due date.

Steps

1. Escrow and split payments are separate features that compose. With split payments alone, Flutterwave auto-settles each seller's collected funds on the due date. Flagging transactions as escrow holds them back: they skip the automatic settlement and each one waits for you to call the settlement endpoint to release funds to the seller, or the refund path to return them to the buyer. So the escrow flow is: collect with the escrow flag, then per transaction call settle to pay the seller or refund to reverse it. Test the full hold, settle, and refund cycle in sandbox before going live.

When to use

You are seeing this: Escrow and split payments are separate features that compose. Use this skill when you run into "Flutterwave escrow: funds wait for your settle call, they skip auto-settlement".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Stack Overflow #56012319 (accepted answer, 3 votes): A marketplace developer testing Flutterwave's escrow payments was confused about how settling and refunding escrow actually works. They understood the docs sentence about calling the settlement endpoint but not the lifecycle: when funds sit in escrow, what releases them to the seller versus returning them to the buyer.

Verified resolution: Escrow and split payments are separate features that compose. With split payments alone, Flutterwave auto-settles each seller's collected funds on the due date. Flagging transactions as escrow holds them back: they skip the automatic settlement and each one waits for you to call the settlement endpoint to release funds to the seller, or the refund path to return them to the buyer. So the escrow flow is: collect with the escrow flag, then per transaction call settle to pay the seller or refund to reverse it. Test the full hold, settle, and refund cycle in sandbox before going live.

Source URL: https://stackoverflow.com/questions/56012319