Transfers

A Transfer in Busha Business is the execution of a previously created Quote. While a Quote describes the proposed terms of an asset transfer, a Transfer is the actual process of moving those assets between sources and destinations according to those terms. Transfers are the core mechanism through which all asset movements happen on the Busha platform. This includes depositing funds, converting between currencies, or sending payouts to external accounts.

​

The Relationship Between Quotes and Transfers

Understanding the relationship between Quotes and Transfers is fundamental to using Busha Business:

• Quote: Describes the proposed transaction (exchange rates, amounts, fees)
• Transfer: Executes the transaction and tracks its progress

​

The workflow is always

1. Create a Quote to lock in rates and terms
2. Present the Quote details to your user for confirmation
3. Create a Transfer using the Quote ID to execute the transaction
4. Monitor the Transfer status to track completion

​

Core Components of a Transfer

When you create or retrieve a Transfer, the response contains several important components:

​

Transfer Identification

• id: The unique identifier for the transfer (e.g., TRF_abc123xyz)
• quote_id: Reference to the Quote that defined the terms of this transfer
• reference: An additional reference identifier for tracking
• profile_id: The ID of the profile (business or customer) that owns this transfer

​

Asset Details

• source_currency: The currency being sent (e.g., BTC, NGN)
• target_currency: The currency being received (e.g., USD, BTC)
• source_amount: The amount of source currency being transferred
• target_amount: The amount of target currency being received
• trade: The type of trade (buy or sell)

​

Transfer Channels (pay_in and pay_out)

The pay_in and pay_out objects specify how assets move into and out of the transfer:

​

pay_in - Where the source assets come from

• Account balance
• Cryptocurrency address
• Bank account (temporary or permanent)
• Mobile money account

​

pay_out - Where the target assets go to

• Account balance
• Cryptocurrency address
• Bank account
• Mobile money account

These objects contain detailed information including addresses, account numbers, blockchain hashes (for crypto), and expiration times (for temporary accounts).

​

Rate and Fees

• rate: The exchange rate object showing the conversion rate used, which currency pair, and the rate type (FIXED/FLOATING)
• fees: An array of fee objects detailing any charges applied to the transfer

​

Status and Timeline

• status: The current status of the transfer (e.g., pending, processing, completed)
• timeline: A detailed object showing the transfer’s progress through various stages
• status_description: A human-readable description of the current status

​

Transfer Status Lifecycle

Understanding the different statuses of your transfers helps you keep track of your funds and provide accurate information to your users. Here’s a concise, tabulated view of what each status means:

Status	Code	Description	Final for
Pending	pending	Transfer initiated; funds not yet received. Waiting for assets to arrive.	—
Processing	processing	Funds received and being handled; progressing to the next stage.	—
Cancelled	cancelled	Transfer cancelled (e.g., user cancelled, quote expired, validation failed); will not proceed.	—
Completed	completed	Transfer fully processed and finalized; assets reached their destination.	—
Funds Received	funds_received	Payment successfully received for a deposit. Often the terminal step for simple deposits.	Deposits
Funds Converted	funds_converted	Currency conversion completed (e.g., NGN→BTC, BTC→USD). Terminal for balance-to-balance conversions.	Conversions
Outgoing Payment Sent	outgoing_payment_sent	Payment initiated and sent on our end; funds are en route to the destination.	—
Funds Delivered	funds_delivered	Funds reached the destination. Typically the final step for payouts and withdrawals.	Payouts/Withdrawals

​

Transfer Completion Flow

Different types of transfers follow different paths through the status lifecycle. Here’s how each type typically progresses:

​

Deposits

A deposit will typically follow this flow and stop at Funds Received:

Deposit Flow for Busha Transfer

​

Conversions

A conversion will conclude with Funds Converted as its final status:

Conversion Flow from currency to currency

​

Payouts / Withdrawals

A payout or withdrawal will reach its final status at Funds Delivered:

Withdrawal Flow on Busha

​

Transfer Timeline

Every Transfer includes a timeline object that provides detailed insight into the transfer’s progress. This object contains:

• total_steps: The total number of steps this transfer will go through
• current_step: Which step the transfer is currently on
• transfer_status: The current high-level status
• events: An array of timeline events showing the history of the transfer

Each event in the timeline includes:

• step: The step number
• done: Whether this step is completed
• status: The status at this step
• title: A short title for the step
• description: A detailed description of what happened
• timestamp: When this event occurred

This timeline is invaluable for providing detailed status updates to your users and for debugging any issues with transfers.

​

Best Practices for Working with Transfers

​

1. Always Create a Quote First

Never attempt to move assets without first creating a Quote. The Quote ensures:

• Rate certainty for your users
• Fee transparency
• Validation that the transfer is possible
• Protection against rate fluctuations during user confirmation

​

2. Check Quote Expiration

Always check the expires_at field of your Quote and create the Transfer before it expires. If a Quote expires, create a new one with current rates.

​

3. Monitor Transfer Status

Use webhooks or polling to monitor transfer status and provide real-time updates to your users. The timeline object provides detailed progress information.

​

4. Handle Failures Gracefully

Transfers can fail for various reasons (insufficient funds, invalid accounts, network issues). Always check the transfer status and status_description for error details, and provide clear feedback to users.

​

5. Store Transfer IDs

Always store the Transfer ID returned when you create a transfer. You’ll need this ID to:

• Check transfer status
• Provide support
• Reconcile transactions
• Generate reports