flutterwave escrow: hold funds, then settle to the seller or refund the buyer

TL;DR

Flutterwave escrow is how a marketplace holds a buyer's payment instead of paying the seller straight away: flag the transaction as escrow when you collect it, and the funds skip auto-settlement and wait. You then release them with a settle call once the buyer confirms the goods or service, or run the refund path to return them to the buyer. Escrow and split payments are separate features that compose, so an escrow payment can still be split, it just does not settle until you say so.

flutterwave escrow

Use this when

• You are building a marketplace or platform where the seller should only be paid after delivery
• You flagged a transaction as escrow and the money is sitting unreleased, and you need to know what releases it
• You expected auto-settlement and it never happened on an escrow transaction
• You need the refund half of the lifecycle: returning held funds to the buyer instead of settling

Not for this skill when

• The payment uses split payments without escrow (those auto-settle on the due date; nothing is held)
• A normal, non-escrow payment is just slow to settle (that is a settlement delay, a different problem)
• Verifying a transaction fails with a not found error (that is a transaction reference problem, see the related skills below)

Steps

1. Collect the payment with the escrow flag set. Escrow is decided at collection time: flagging the transaction is what holds the funds back from the normal settlement run.

Expected: the payment succeeds and the funds sit held instead of appearing in the seller's settlement.

2. Understand what changes versus split payments alone. With split payments alone, Flutterwave auto-settles each seller's collected funds on the due date. Flagging a transaction as escrow skips that automatic settlement: each held transaction waits for your explicit call, even if it also carries split instructions.

Expected: you stop waiting for a due date that will never release an escrow transaction on its own.

3. Release to the seller with the settlement endpoint once the buyer confirms. When the goods arrive or the service is done, call settle for that transaction to pay the seller.

Expected: the held funds move to the seller. Nothing else releases them; time passing does not.

4. Or return the money through the refund path. If the deal falls through, refund the transaction instead of settling, and the held funds go back to the buyer.

Expected: the buyer is made whole and the transaction closes with no settlement to the seller.

5. Test the full cycle in sandbox before going live. Run hold, settle, and refund end to end in the sandbox, including the buyer-never-confirms case, so your release and timeout logic is proven before real money sits in escrow.

Expected: all three outcomes (settle, refund, still held) behave the way your platform promises buyers and sellers.

Variant phrasings

flutterwave escrow payments explained

The lifecycle in the TL;DR: collect with the escrow flag, hold, then settle to the seller or refund the buyer. There is no automatic middle step.

flutterwave escrow funds not settling

That is escrow working as designed, not a stuck payment. Held funds skip auto-settlement by definition; call settle (step 3) to release them.

flutterwave escrow vs split payments

Split payments divide money between sellers and auto-settle on the due date. Escrow decides when money moves at all. They compose: a split payment flagged as escrow is divided as instructed but only released on your settle call.

how do i release flutterwave escrow funds

Per transaction, with the settlement endpoint, after the buyer confirms (step 3). There is no bulk auto-release and no due-date shortcut.

Why this happens

Escrow exists to protect the buyer in a marketplace: the platform proves it holds the money, and the seller only gets paid after delivery. Flutterwave implements that by separating collection from settlement for flagged transactions. The confusion in the original report came from reading escrow and split payments as one feature; they are two features that compose, and the escrow flag is the one that turns off the automatic settlement split payments normally get.

Edge cases

• A transaction that is never settled or refunded just stays held; build your own reminder and timeout flow for buyers who never confirm.
• Sandbox first is not optional here: the settle and refund calls are per transaction, and a wiring mistake in production means real seller money waits on a debug session.
• No specific versions are mentioned in the source material, so treat the lifecycle as generally applicable and check the examples against the Flutterwave docs for your integration.

Tool compatibility

Flutterwave payments with escrow and split payments, including marketplace and platform integrations collecting on behalf of sellers. Verified against the accepted Stack Overflow answer below; endpoint details follow the Flutterwave docs for your API version.

Related skills

• flutterwave "no transaction was found" on verify, wrong transaction reference: https://vectle.com/skills/skl_-yHA1a8QenVFt6Vw81GN-Q
• Fix Flutterwave Node v3 Transaction.verify failing: https://vectle.com/skills/skl_vF-B1iLVqKMDig4HCnDtoQ

Provenance

Resolved from Stack Overflow question 56012319 (accepted answer): a marketplace developer testing Flutterwave escrow payments asked how settling and refunding escrow actually works.

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