Module 4: Building a Full Payout Lifecycle: Quotes, Funding, Processing, Completion

Introduction

You cannot manage what you do not understand. As a PM building payout products — especially Bitcoin- or stablecoin-powered payouts — you must know the full transaction lifecycle intimately.

You must know:

What happens at each stage

What can fail or delay at each stage

How your systems and users are impacted at each stage

How to detect and recover from issues before users notice.

In this module, we break down the full payout lifecycle.

This module is conceptual. For the request and response shapes behind each phase, see the Payouts API reference.

The Five Major Phases of a Payout

stage	description
1	Quote Requested
2	Payout Initiated
3	Funding Confirmed
4	Fiat Payout Processing
5	Completion (Success, Failure, or Expiry)

Each stage updates the Trip object internally, and triggers specific webhook events externally to your systems.

Phase 1: Quote Requested

The user (or your system) requests a quote for a payout:

Source asset (BTC, USDT)

Destination currency (NGN, GHS, KES, etc.) — the live list comes from Get Supported Countries

Amount to deliver — check it against the corridor floor and ceiling from Get Limits before quoting.

The platform responds with:

Funding amount required

Expiry timestamp (payment window)

Locked FX rate

Quote ID.

Key Risks at this Stage:

If user delays funding, quote expires.

FX volatility exposure if you hold quotes too long.

Best Practices:

Display funding expiry clearly to user.

Encourage fast action to avoid expired quotes.

API Reference: Create Payouts Quote, Get Limits

Phase 2: Payout Initiated

User accepts the quote and initiates a payout request:

Provides beneficiary details (bank account, mobile wallet) — the accepted fields differ per country, listed under Get Country Details, and bank codes come from Get Banks

Provides reference ID (optional, for tracking)

System returns:

Payment address (or Lightning invoice)

Payout id for lifecycle tracking

Payment instructions.

Key Risks at this Stage:

Incorrect beneficiary details entered by user.

Payment address confusion (wrong chain, wrong invoice).

Best Practices:

Validate beneficiary formats before initiation — Account Lookup name-resolves the account and returns the account_name to confirm back to the user.

Auto-select correct blockchain chain if stablecoins are used.

API Reference: Account Lookup, Initialize Payout, then Finalize Payout

Phase 3: Funding Confirmed

User sends payment to the funding address:

Blockchain or Lightning network detects transaction (assetReceivedAt).

Wait for enough confirmations to consider payment secure (assetConfirmedAt).

Only after full confirmation does fiat payout processing start.

Key Risks at this Stage:

Underpayment (user sends less than required).

Overpayment (user sends more than required).

Payment delayed by network congestion (e.g., Bitcoin mempool backlog).

Payment received after quote expiry.

Best Practices:

Build alerts if funding confirmation lags beyond expected time.

Allow partial payout (adjusted delivery) if underpayment occurs.

Auto-credit excess funds or manage via internal balance.

API Reference: no endpoint funds a payout — the customer pays on-chain, and you learn the outcome from Payout Webhooks or by polling Get Payout by ID.

Phase 4: Fiat Payout Processing

After funding is confirmed:

Platform initiates fiat payout to beneficiary:

Bank account

Mobile money wallet

Fiat settlement systems have their own speeds:

Nigeria NIP — minutes

UK Faster Payments — minutes

SEPA — hours to next day

Which rails a corridor actually offers is returned by Get Country Details. Corridors reached over correspondent banking rather than a local rail run through SWIFT Payouts, which has its own quote, initialize and finalize steps.

Key Risks at this Stage:

Bank rejects payout (wrong account number, compliance block).

Mobile money systems down or delayed.

Liquidity shortages on fiat side.

System downtime.

Best Practices:

Track payout processing latency internally per corridor.

Provide user notifications at "payout started" phase.

Build automatic retries for transient payout failures.

API Reference: Get Country Details, SWIFT Payouts

Phase 5: Completion

The payout either:

Succeeds — funds arrive at beneficiary.

Fails — payout rejected, refunded, or requires manual resolution.

Expires — funding not received in time.

At this stage:

Webhook events are triggered:

payout.transfer.success

payout.transfer.failed

Trip object records completionTime and calculates timeToFinish.

Key Risks at this Stage:

Silent payout failures if monitoring is weak.

SLA breaches if payouts take longer than expected.

Customer trust erosion if not communicated properly.

Best Practices:

Confirm success explicitly to users.

Proactively contact users if failures occur.

Monitor average timeToFinish per payout corridor and product.

API Reference: Get Payout by ID, Payout Webhooks

Full Payout Flow Visualization

Practical Example

Imagine you are building a dashboard for internal ops monitoring.

Every view below is built on List Payouts, filtered by status and date, with Get Payout by ID behind each row for the full timeline.

Design views that allow your team to see:

All payouts currently stuck in "awaiting funding confirmation."

All payouts taking longer than 15 minutes at "processing" stage.

All payouts where beneficiary rejection rates spike above 2% in a corridor.

You are not just building product features.

You are building operational control centers.

PM Action Checklist (End of Module 3)

Map every payout through the five-phase lifecycle.

Define internal monitoring points at each transition.

Build webhook handlers that can reconstruct full payout journeys using the payout id or your own reference — verify every event first, per Verifying Events.

Design user communication to align with real lifecycle phases.

Set operational SLA targets per phase and per payout corridor.

Closing Reflection

Payout products do not live at the surface of APIs.

They live inside the invisible flows of funding, confirmation, settlement, and finality.

Master the lifecycle.

Master the payout.

In the next module, we will dive into

Error Handling in Money Movement Products