Webhooks

When you make a transfer request, you typically have to wait for a payment to be sent into/out of the platform before that transfer can be updated as done. This can be achieved by either polling the GET Transfer API or by listening to a webhook URL.

Webhook is the recommended way to listen for updates for a transfer request as the polling alternative will not be reliable due to poor connection on the client side which you do not have control over.

Create A Webhook URLCopied!

A webhook URL is simply a POST endpoint that Busha API server sends updates to. The URL needs to receive and parse a JSON request and return a 200 OK response.

Set Up WebhookCopied!

After you have created your webhook URL, you need to visit the developer tools section on your dashboard to register the URL. Profile > Developer Tools > Webhooks

Click on the “Create a Webhook” button. You should see an input form like this:

Enter a name for your webhook and include the full path to the webhook URL you created in the previous step. Click on the “Create webhook” button, then copy your secret key.

Listen for EventsCopied!

Webhooks receive the following events from Busha:

Sample Event Payload:

{
  "business_id": "BUS_tg6yujbZ1nMu5BLQkPGGO",
  "event": "transfer.funds_converted",
  "data": {
    "id": "TRF_BaAUvCTlZCt3hu3OO4u8P",
    "profile_id": "BUS_tg6yujbZ1nMu5BLQkPGGO",
    "quote_id": "QUO_5CnpikeQJEKQoDcnOsdkU",
    "source_currency": "NGN",
    "target_currency": "USDT",
    "source_amount": "10000",
    "target_amount": "5.728032",
    "rate": {
      "product": "USDTNGN",
      "rate": "1745.8",
      "side": "buy",
      "type": "FIXED",
      "source_currency": "NGN",
      "target_currency": "USDT"
    },
    "fees": [],
    "status": "completed",
    "created_at": "2025-02-21T09:55:20.852345Z",
    "updated_at": "2025-02-21T09:55:22.365451Z"
  }
}

Transfer Status DevelopmentCopied!

The following section aims to show how a transfer can develop from one status to another. This will you understand how to properly handle and anticipate webhook events.

Transfer.Pending:

This is the initial status for all transfers. All transfers start as pending and a pending transfer can morph into only two next statuses:

• transfer.cancelled

• transfer.processing

Transfer.Cancelled:

A cancelled transfer means that the transfer was unable to continue and can not begin processing. Hence, this is a final state that can not further change.

Transfer.Processing:

A processing transfer means that the transfer has started work and is already making the money movement from destination to source. A processing transfer can change into any of these statuses depending on the transfer type:

• transfer.outgoing_payment_sent

• transfer.funds_received

• transfer.funds_converted

Transfer.OutgoingPaymentSent:

An outgoing_payment_sent status represents any transfer that involves sending money out of the Busha platform to an external bank account or an external wallet address. It is not a final status, the outgoing_payment_sent status can morph into a final funds_delivered status

Funds.Delivered:

This is a final status that communicates that a payout transfer has been delivered successfully in the specified destination.

Funds.Received:

The funds_received status communicates that a Deposit into a Busha Balance has been successful. This could be a final status for all deposit transfers, however, in a scenario where the source currency is not the same as the target currency, then this transfer will further change into a funds_converted status.

Funds.Converted:

The funds_converted status communicates that a conversion transfer has been done successfully. This is also the same status that communicated the successful Buy/Sell Trade.

Transfer Status Change MapCopied!

Conversions and Trades(Buy/Sell) Status Change:

pending → processing → funds_converted

Payouts Status Change:

pending → processing → outgoing_payment_sent → funds_delivered

Deposit Status Change:

pending → processing → funds_received

On-Ramp (External Fiat → Crypto):

pending → processing → funds_received → funds_converted