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

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 quote_id

Save the amount and expiry.

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 id and reference.

Present the address to the user immediately.

Remember: Payment must happen before expiry.

Step 3: Fund the Payout

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

Exact amount as per amount.

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 status (quote, initiated, processing, success, failed, expired)

Settlement details (settlement_amount, exchange_rate, beneficiary)

Timeline fields (created_at, updated_at, expiry)

Useful for internal dashboards and monitoring.

Best Practices for Building a Reliable Payout Flow

Save and track the id and reference for every payout.

Always validate payment timing against expiry.

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 payment_eta metrics for operational health.

Full Payout Lifecycle Example (Quick)

action	bitnob response	developer system
Request Quote	Returns quote_id	Save quote_id
Initiate Payout	Returns id, address	Save id, 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

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.