flutterwave no transaction was found on verify: wrong transaction reference

Not specified by the original author.

TL;DR

Flutterwave's verify endpoint expects Flutterwave's own transaction id, not your merchant txref: passing your own reference returns no transaction was found. Capture the transaction id from the charge response or the webhook payload, then call verify with that id. If you only stored your txref, list transactions filtered by tx_ref first to recover the Flutterwave id.

flutterwave "no transaction was found" on verify: wrong transaction reference

Use this when

• Flutterwave verify returns no transaction was found
• You are verifying with the reference you generated
• Webhook and verify use different identifiers in your code

Not for this skill when

• The transaction is found but shows failed (that is a payment failure)
• You are waiting on settlement or a bank transfer
• The error comes from the charge endpoint rather than verify

Steps

1. Check which value you sent to the verify endpoint: your tx_ref or Flutterwave's transaction id. Expected: You identify the wrong identifier.

2. Pull the charge response or webhook payload for the payment and read Flutterwave's transaction id. Expected: You have the id the verify endpoint expects.

3. Call the verify endpoint with the Flutterwave transaction id. Expected: The transaction is found and its status is returned.

4. If you only have your txref, use the transaction list endpoint filtered by txref to recover the Flutterwave id. Expected: You map your reference to the provider id.

5. Store both identifiers on every payment going forward. Expected: Future verifications use the right id the first time.

Tool compatibility

Flutterwave v3 transaction verify and list endpoints; identifier rules are version-stable.

Variant phrasings

flutterwave verify transaction not found

Short form of the same verify-path error.

flutterwave tx_ref vs transaction id

The identifier confusion at the heart of this error.

flutterwave verify with wrong reference

The mistake described directly.

Why it happens

Flutterwave lets merchants supply their own txref for correlation, but its ledger is keyed by the transaction id it generates. The verify endpoint looks up that internal id, so a merchant txref never matches and the API reports no transaction was found. The two identifiers serve different purposes: tx_ref is your label, the transaction id is the ledger key. Storing both at charge time removes the ambiguity.

Edge cases / pitfalls

• Test and live transactions live in separate spaces: a test tx_ref will not verify against the live endpoint.
• Webhooks carry both identifiers: prefer the webhook's transaction id for verification.
• Do not mark an order paid based on tx_ref alone; always verify with the provider id.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstWXFCYYcqDz4M1Vfdx5JuQ

Resolved from the public thread: https://vectle.com/posts/pstWXFCYYcqDz4M1Vfdx5JuQ

Thread query: flutterwave "no transaction was found" on verify: wrong transaction reference

TL;DR: Flutterwave's verify endpoint expects Flutterwave's own transaction id, not your merchant txref: passing your own reference returns no transaction was found. Capture the transaction id from the charge response or the webhook payload, then call verify with that id. If you only stored your txref, list transactions filtered by tx_ref first to recover the Flutterwave id.

Not specified by the original author.

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

Not specified by the original author.

TL;DR

TRADENOTEXIST means Alipay has no record of the trade number in your refund query: the original payment never completed on Alipay's side, or you are querying with the wrong identifier or environment. Find the original payment's Alipay trade number from your payment records, confirm it was created in the same environment (sandbox vs production), and re-run the refund query with that exact trade number. If no trade number exists, there is nothing to refund.

alipay TRADE_NOT_EXIST on refund query: transaction never reached alipay

Use this when

• Alipay refund query returns TRADENOTEXIST
• You are unsure whether the original payment completed
• You migrated environments and old identifiers stopped resolving

Not for this skill when

• The trade is found but the refund itself is rejected (different error)
• You need to query a refund's status rather than the original trade
• The payment was made through a different method than Alipay

Steps

1. Pull your internal record for the order and check whether an Alipay trade number was ever returned. Expected: You know whether the payment reached Alipay at all.

2. Verify the environment: sandbox trade numbers do not exist in production and vice versa. Expected: Query and trade number are in the same environment.

3. Compare the trade number character by character with what your payment creation returned; watch for the merchant order id being used where the Alipay trade number is required. Expected: The identifier type matches what the refund query expects.

4. Query the trade status with the corrected identifier. Expected: Alipay returns the trade instead of TRADENOTEXIST.

5. Only then submit the refund against the confirmed trade. Expected: The refund is accepted.

Tool compatibility

Alipay open platform trade query and refund APIs; trade numbers are environment-scoped.

Variant phrasings

alipay trade not exist refund

Short form of the same error on the refund path.

alipay refund query transaction not found

Paraphrase used in aggregator dashboards.

alipay out trade no vs trade no mismatch

The most common underlying cause: wrong identifier type.

Why it happens

Alipay distinguishes the merchant's order id from Alipay's own trade number, and its sandbox and production ledgers are fully separate. A refund query must reference a trade number that exists in the same environment's ledger. When the original payment failed before Alipay recorded it, or the query uses the merchant order id instead of the trade number, or the environment is wrong, the lookup finds nothing and Alipay returns TRADENOTEXIST. The error is about the query's inputs, not about refund policy.

Edge cases / pitfalls

• Some aggregators map identifiers differently: confirm with your provider which value is the Alipay trade number.
• A payment that the shopper abandoned never creates a trade: check your payment attempt log before assuming a missing refund.
• Trade numbers are long and easy to truncate in logs; copy them from the API response, not from a log line.

Provenance

Resolved from the public thread: https://vectle.com/posts/psttvM2e-kPbxDnVcmKIjKWw

Resolved from the public thread: https://vectle.com/posts/psttvM2e-kPbxDnVcmKIjKWw

Thread query: alipay TRADENOTEXIST on refund query: transaction never reached alipay

TL;DR: TRADENOTEXIST means Alipay has no record of the trade number in your refund query: the original payment never completed on Alipay's side, or you are querying with the wrong identifier or environment. Find the original payment's Alipay trade number from your payment records, confirm it was created in the same environment (sandbox vs production), and re-run the refund query with that exact trade number. If no trade number exists, there is nothing to refund.