Module 4: The payout lifecycle, stage by stage

A payout is not one event. It is a record that moves through five stages, and it can stop at any of them. You cannot monitor a process you cannot describe, so this module describes it.

​

What you will learn

• The five stages, and what changes at each one
• What fails at each stage, and how you detect it
• Which timestamps let you answer “where is my money”

​

The five stages

Each transition writes a timestamp to the payout’s trip object, and some transitions send a webhook. Full detail is in Statuses and webhook events.

​

Stage 1: The quote

You request a quote with the source asset, the destination currency, and the amount to deliver. You receive a funding amount, a locked rate, an expiry time, and a quote id. What fails here. The user takes too long and the quote expires. If you hold quotes open, you carry the price movement yourself. What to do. Show the expiry as a countdown, not a timestamp. Fetch a new quote rather than reusing an old one.

​

Stage 2: Initialization

The user accepts the quote and supplies the beneficiary: a bank account or a mobile money wallet. You receive a funding address or a Lightning invoice. What fails here. The beneficiary details are wrong, or the user pays on a different chain from the address you issued. What to do. Validate the account before you initialize, using Account lookup. Show the chain beside the address, and never display an address without it.

​

Stage 3: Funding

The user pays. The network reports the transaction, then confirms it. Delivery only starts after confirmation. The Trip records asset_received when the funding arrives. Until then, the payout stays waiting for the deposit. What fails here.

• The user sends less than the funding amount.
• The user sends more than the funding amount.
• Network congestion delays confirmation.
• The payment arrives after the quote expired.

What to do. Alert when funding stays unconfirmed longer than the corridor’s normal time. A shortfall beyond a very small tolerance is refused, so decide how you’ll handle the user’s funds if that happens. Decide where an overpayment goes.

​

Stage 4: Delivery

The local rail moves the money to the beneficiary. Each rail has its own speed. What fails here. The bank rejects the account. The mobile money operator is down. The rail runs out of local liquidity. What to do. Measure delivery time per corridor, not as one average. Tell the user when delivery starts. Retry only failures that are safe to retry.

​

Stage 5: Completion

The payout reaches SUCCESS or FAILED, or expires without funding and moves to EXPIRED. Five events report this: payouts.initialized, payouts.processing, payouts.withdrawal.success, payouts.withdrawal.expired, and payouts.withdrawal.failed. What to do. Confirm success to the user explicitly. Contact the user yourself when a payout fails, before they contact you. Track how long each corridor takes from quote to completion.

​

The full flow

​

Exercise: design the operations view

Your operations team needs one screen. Build it to answer three questions:

1. Which payouts are waiting for funding confirmation, and for how long?
2. Which payouts have been PROCESSING for longer than 15 minutes?
3. Which corridors have a rejection rate above 2% today?

A team that can answer those three questions finds problems before users report them. A team that cannot is waiting for complaints.

​

Checklist for product managers

• Map every payout in your product to these five stages.
• Define an alert for each transition that can stall.
• Store the payout id and your reference so you can rebuild any payout’s history.
• Match your user messages to the real stages, not to your API calls.
• Set a target delivery time per corridor, and measure against it.

​

Summary

A payout product is judged on what happens between the request and the arrival. Learn the five stages, watch each transition, and the failures become visible while you can still fix them.