Building a Full Payout Flow

This section walks you through how to integrate and operate a complete end-to-end payout flow with Bitnob.

You'll learn how to:

Request a Quote

Initiate a Payout

Fund the Payout

Handle Webhooks

Confirm Completion

Full Flow Diagram

sequenceDiagram

participant Client App

participant Bitnob API

participant Blockchain/Lightning

participant Bank/Mobile Money

Client App -->> Bitnob API: POST /payouts/quotes

Bitnob API -->> Client App: Quote details (funding amount, expiry, quoteId)

Client App -->> Bitnob API: POST /payouts/initiate with quoteId + beneficiary

Bitnob API -->> Client App: Payment address/invoice + TripId

Client App -->> Blockchain/Lightning: Pays to provided address

Blockchain/Lightning -->> Bitnob API: Payment confirmed

Bitnob API -->> Client App: Webhook payouts.asset.received

Bitnob API -->> Bank/Mobile Money: Process fiat payout

Bank/Mobile Money -->> Bitnob API: Payout result

Bitnob API -->> Client App: Webhook payouts.withdrawal.success or payouts.withdrawal.failed

Step 1: Request a Quote

You must always start by requesting a quote for the intended payout.

Endpoint

Example Request

json

Example Response

json

Save the quoteId

Save the fundingAmount and expiresAt.

Step 2: Initiate the Payout

Once you have the quote, initiate the payout with the beneficiary details.

Endpoint

Example Request

json

Example Response

json

Save the tripI and reference.

Present the paymentAddress to the user immediately.

Remember: Payment must happen before expiresAt.

Step 3: Fund the Payout

Your application (or your user) must pay the paymentAddress.

Exact amount as per amountToPay.

Within the expiry window.

Using the correct asset and chain (BTC, USDT TRC20, Lightning, etc.).

Recommend customers use high enough gas fees for faster confirmations.

Step 4: Handle Webhooks

'Once payment is detected and payout processing starts, Bitnob sends webhook notifications.

You must handle:

WEBHOOK-EVENT	WHAT IT MEANS
payouts.asset.received	Funding payment received successfully.
payouts.withdrawal.processing	Fiat payout to beneficiary started.
payouts.withdrawal.success	Payout delivered successfully.
payouts.withdrawal.failed	Payout failed after funding.
payouts.withdrawal.expired	No payment received in time; payout canceled.

Example Webhook Payload: Payment Received

json

At this point, Bitnob will automatically move to fiat payout phase.

Example Webhook Payload: Payout Success

Example Webhook Payload

json

Update your internal database: mark this payout as delivered.

Step 5: Optional — Poll for Trip Status

At any time, you can fetch the latest Trip status.

Endpoint

Response will show:

Current fundingStatus (pending, paid, expired)

Current payoutStatus (awaiting_payment, processing, success, failed)

Timeline fields (submittedAt, assetReceivedAt, processingAt, settlementAt, etc.)

Useful for internal dashboards and monitoring.

Best Practices for Building a Reliable Payout Flow

Save and track the tripId for every payout.

Always validate payment timing against expiresAt.

Always listen for webhooks — don't rely on polling alone.

Design idempotent webhook handlers — Bitnob may retry webhooks if your server is slow.

Handle underpayment or overpayment gracefully.

Monitor timeToFinish metrics for operational health.

Full Payout Lifecycle Example (Quick)

Action	Bitnob Response	Developer System
Request Quote	Returns quoteId	Save quoteId
Initiate Payout	Returns tripId, payment address	Save tripId, present payment UI
Fund Payment	Pay address	Start listening for webhooks
Payment Detected	Webhook: asset.received	Mark as funded
Fiat Processing	Webhook: withdrawal.processing	Update UI to 'In Progress'
Success	Webhook: withdrawal.success	Mark payout as complete
Failure	Webhook: withdrawal.failed	Flag payout for retry or support investigation
Expired	Webhook: withdrawal.expired	Alert user to retry with new quote

{% sections name="finalThought" label="Final Thought %}

Final Thought

Integrating payouts is not just sending API calls.

It's managing funding, timing, liquidity, settlement, and user expectations cleanly.

This guide gives you the map.

Your product can now move money globally — powered by Bitcoin and stablecoins underneath, but feeling seamless for end users.