Skip to main content
Busha sends webhook notifications to your server when events happen on your account. Use webhooks to automate workflows and keep your application in sync with Busha.

​
Why Use Webhooks?

Webhooks eliminate the need to poll the API repeatedly instead, Busha notifies you instantly when something happens. Common use cases:
  • Confirm order fulfillment after payment
  • Update order status in your database
  • Send customer receipts automatically
  • Trigger inventory updates
  • Notify customers of payment status

​
Transfer Events

Transfer events track the complete lifecycle of all fund movements on Busha, including:
  • Deposits - Receiving crypto or fiat into your Busha account
  • Conversions - Converting between currencies (crypto-to-fiat, fiat-to-crypto, crypto-to-crypto)
  • Payouts - Sending funds to bank accounts or external wallets

​
transfer.pending

Sent when: A new transfer is created and awaiting funds. Use case: Display “Awaiting Payment” status to your customer. 
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "transfer.pending",
  "data": {
    "id": "TRF_nH6ZB1JeV5Sp",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "quote_id": "QUO_QoURQhUd7jrq",
    "description": "Sold BTC",
    "sub_description": "For NGN",
    "source_currency": "BTC",
    "target_currency": "NGN",
    "source_amount": "0.00018064",
    "target_amount": "25000.21",
    "trade": "sell",
    "status": "pending",
    "pay_in": {
      "address": "tb1q7vda878dzccf5v8p0edulwhryyg973s8hkwqzz",
      "expires_at": "2025-12-04T16:41:11.780867Z",
      "network": "BTC",
      "type": "address"
    },
    "timeline": {
      "total_steps": 0,
      "current_step": 0,
      "transfer_status": "",
      "events": []
    },
    "created_at": "2025-12-04T15:41:11.709116315Z"
  }
}

​
transfer.processing

Sent when: Funds have been sent and are being actively processed. Use case: Update UI to show “Processing…” status while Busha handles the transfer internally. 
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "transfer.processing",
  "data": {
    "id": "TRF_Bz6i6C5HaS7t",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "source_currency": "BTC",
    "target_currency": "NGN",
    "source_amount": "0.0001841",
    "target_amount": "25000.17",
    "status": "processing",
    "created_at": "2025-12-05T13:12:57.582284Z",
    "updated_at": "2025-12-05T13:13:30.123456Z"
  }
}

​
transfer.funds_received

Sent when: Funds have been successfully received into your Busha account. Use case:
  • For deposits: This is the final status - funds are now in the account
  • For conversions/payouts: This is an intermediate step before further processing
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "transfer.funds_received",
  "data": {
    "id": "TRF_Bz6i6C5HaS7t",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "source_currency": "BTC",
    "target_currency": "NGN",
    "source_amount": "0.0001841",
    "target_amount": "25000.17",
    "status": "funds_received",
    "pay_in": {
      "address": "tb1qjd48um52dc54f7kd79kgjsfx2vlr3ae6pd5683",
      "network": "BTC",
      "type": "address",
      "blockchain_hash": "busha_108b4d46345e7e3753abb6c095d7883f8c81d27dd81f894239d7c6a18b28a9d9",
      "blockchain_url": "https://live.blockcypher.com/btc/tx/busha_108b4d46345e7e3753abb6c095d7883f8c81d27dd81f894239d7c6a18b28a9d9"
    },
    "timeline": {
      "total_steps": 2,
      "current_step": 1,
      "transfer_status": "funds_received",
      "events": [
        {
          "step": 1,
          "done": true,
          "status": "funds_received",
          "title": "Crypto Received",
          "description": "Funded from Balance"
        }
      ]
    },
    "created_at": "2025-12-05T13:12:57.582284Z",
    "updated_at": "2025-12-05T13:14:38.243849Z"
  }
}

​
transfer.funds_converted

Sent when: Currency conversion is complete (crypto-to-fiat, fiat-to-crypto, or crypto-to-crypto). Use case:
  • For conversion-only transfers: This is the final status
  • For payment flows: Mark order as “Paid” and fulfill the order
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "transfer.funds_converted",
  "data": {
    "id": "TRF_Bz6i6C5HaS7t",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "quote_id": "QUO_yPfvBpxstyjp",
    "description": "Sold BTC",
    "sub_description": "For NGN",
    "source_currency": "BTC",
    "target_currency": "NGN",
    "source_amount": "0.0001841",
    "target_amount": "25000.17",
    "trade": "sell",
    "rate": {
      "product": "BTCNGN",
      "rate": "135796707.37",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "BTC",
      "target_currency": "NGN"
    },
    "fees": [],
    "status": "funds_converted",
    "timeline": {
      "total_steps": 2,
      "current_step": 2,
      "transfer_status": "funds_converted",
      "events": [
        {
          "step": 1,
          "done": true,
          "status": "funds_received",
          "title": "Crypto Received",
          "description": "Funded from Balance"
        },
        {
          "step": 2,
          "done": true,
          "status": "funds_converted",
          "title": "Funds Converted",
          "description": "Money has been added to your wallet."
        }
      ]
    },
    "created_at": "2025-12-05T13:12:57.582284Z",
    "updated_at": "2025-12-05T13:14:38.243849Z"
  }
}

​
transfer.outgoing_payment_sent

Sent when: Outgoing payment has been initiated and is being processed for delivery. Use case: Update UI to show “Payment In Transit” for payouts/withdrawals. 
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "transfer.outgoing_payment_sent",
  "data": {
    "id": "TRF_mWVskyPQ0nyW",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "source_currency": "NGN",
    "target_currency": "NGN",
    "source_amount": "5000",
    "target_amount": "5000",
    "status": "outgoing_payment_sent",
    "pay_out": {
      "type": "bank_transfer",
      "recipient_details": {
        "account_name": "John Doe",
        "account_number": "0123456789",
        "bank_name": "First Bank of Nigeria"
      }
    },
    "created_at": "2025-12-05T14:20:00.000000Z",
    "updated_at": "2025-12-05T14:21:30.000000Z"
  }
}

​
transfer.funds_delivered

Sent when: Funds have been successfully delivered to the recipient’s bank account or external wallet. Use case:
  • For payouts/withdrawals: This is the final status
  • Send final confirmation to customer that funds have been delivered
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "transfer.funds_delivered",
  "data": {
    "id": "TRF_mWVskyPQ0nyW",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "source_currency": "NGN",
    "target_currency": "NGN",
    "source_amount": "5000",
    "target_amount": "5000",
    "status": "funds_delivered",
    "pay_out": {
      "type": "bank_transfer",
      "recipient_details": {
        "account_name": "John Doe",
        "account_number": "0123456789",
        "bank_name": "First Bank of Nigeria"
      }
    },
    "created_at": "2025-12-05T14:20:00.000000Z",
    "updated_at": "2025-12-05T14:22:15.000000Z"
  }
}

​
transfer.cancelled

Sent when: Transfer is cancelled (due to expiration, user cancellation, or system cancellation). Use case: Update order status to “Cancelled” and notify customer. 
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "transfer.cancelled",
  "data": {
    "id": "TRF_aKn8Z3Cmtc8a",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "source_currency": "USDC",
    "target_currency": "NGN",
    "source_amount": "16.91200347",
    "target_amount": "25000",
    "status": "cancelled",
    "created_at": "2025-12-04T12:06:47.648775Z",
    "updated_at": "2025-12-04T12:36:47.648775Z"
  }
}

​
transfer.failed

Sent when: Transfer fails due to an error (insufficient funds, network issues, invalid recipient details, etc.). Use case: Alert support team and notify customer of the failure. 
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "transfer.failed",
  "data": {
    "id": "TRF_failed123",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "source_currency": "BTC",
    "target_currency": "NGN",
    "source_amount": "0.0001",
    "target_amount": "15000",
    "status": "failed",
    "error": {
      "code": "insufficient_funds",
      "message": "Insufficient balance to complete transfer"
    },
    "created_at": "2025-12-05T10:00:00.000000Z",
    "updated_at": "2025-12-05T10:05:00.000000Z"
  }
}

​
Payment Request Events

Payment request events track the lifecycle of payment links created through the Busha Business API. These are typically used for e-commerce integrations, invoicing, and customer payment flows.

​
payment_request.created

Sent when: A new payment link is generated. Use case: Log payment request creation, track link generation, or send payment link to customer via email/SMS. 
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "payment_request.created",
  "data": {
    "id": "PAYR_NwSBgvVszPvA",
    "additional_info": {
      "email": "[email protected]",
      "name": "John Doe",
      "phone_number": "+2348012345678",
      "source": "checkout_page"
    },
    "created_at": "2025-12-09T09:51:03.422936437Z",
    "expires_at": "2025-12-09T10:51:03.361946Z",
    "fees": [],
    "merchant_info": {
      "email": "[email protected]",
      "name": "Liverpool"
    },
    "reference": "PAYR_NwSBgvVszPvA",
    "source": "payment_link",
    "source_id": "58HgbtNDA34Z",
    "status": "created",
    "source_amount": "6.76480139",
    "source_currency": "USDC",
    "target_amount": "10000",
    "target_currency": "NGN",
    "rate": {
      "product": "USDCNGN",
      "rate": "1478.24",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "USDC",
      "target_currency": "NGN"
    },
    "timeline": {
      "total_steps": 0,
      "current_step": 0,
      "transfer_status": "",
      "events": []
    },
    "updated_at": "2025-12-09T09:51:03.422936519Z"
  }
}

​
payment_request.pending

Sent when: Payment request is awaiting customer payment. Use case: Track pending payments in your dashboard, send reminder emails, or update order status to “Payment Pending”. 
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "payment_request.pending",
  "data": {
    "id": "PAYR_NwSBgvVszPvA",
    "additional_info": {
      "email": "[email protected]",
      "name": "",
      "phone_number": "",
      "source": ""
    },
    "created_at": "2025-12-09T09:51:03.422936437Z",
    "expires_at": "2025-12-09T10:51:03.361946Z",
    "fees": [],
    "merchant_info": {
      "email": "[email protected]",
      "name": "Liverpool"
    },
    "pay_in": {
      "address": "GDHHXPUSZK2OYHEVAP7GG6MTDWY2VQ4V5JBTIKFEV526RT6QYF23BSXD",
      "expires_at": "2025-12-09T10:51:03.361946Z",
      "memo": "1812242366",
      "network": "XLM",
      "type": "address"
    },
    "rate": {
      "product": "USDCNGN",
      "rate": "1478.24",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "USDC",
      "target_currency": "NGN"
    },
    "reference": "PAYR_NwSBgvVszPvA",
    "source": "payment_link",
    "source_amount": "6.76480139",
    "source_id": "58HgbtNDA34Z",
    "status": "pending",
    "target_amount": "10000",
    "timeline": {
      "total_steps": 0,
      "current_step": 0,
      "transfer_status": "",
      "events": []
    },
    "updated_at": "2025-12-09T09:51:03.422936519Z",
    "source_currency": "USDC",
    "target_currency": "NGN"
  }
}

​
payment_request.completed

Sent when: Customer successfully completes payment via payment link. Use case: Fulfill order, send confirmation email, update inventory, and mark order as “Paid”. This is the key event for confirming successful payment. 
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "payment_request.completed",
  "data": {
    "id": "PAYR_NwSBgvVszPvA",
    "additional_info": {
      "email": "[email protected]",
      "name": "John Doe",
      "phone_number": "+2348012345678",
      "source": "checkout_page"
    },
    "created_at": "2025-12-09T09:51:03.422936437Z",
    "completed_at": "2025-12-09T10:15:45.123456Z",
    "fees": [],
    "merchant_info": {
      "email": "[email protected]",
      "name": "Liverpool"
    },
    "pay_in": {
      "address": "GDHHXPUSZK2OYHEVAP7GG6MTDWY2VQ4V5JBTIKFEV526RT6QYF23BSXD",
      "expires_at": "2025-12-09T10:51:03.361946Z",
      "memo": "1812242366",
      "network": "XLM",
      "type": "address",
      "blockchain_hash": "abc123def456...",
      "blockchain_url": "https://stellarchain.io/tx/abc123def456..."
    },
    "rate": {
      "product": "USDCNGN",
      "rate": "1478.24",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "USDC",
      "target_currency": "NGN"
    },
    "reference": "PAYR_NwSBgvVszPvA",
    "source": "payment_link",
    "source_amount": "6.76480139",
    "source_id": "58HgbtNDA34Z",
    "status": "completed",
    "target_amount": "10000",
    "source_currency": "USDC",
    "target_currency": "NGN",
    "timeline": {
      "total_steps": 2,
      "current_step": 2,
      "transfer_status": "completed",
      "events": [
        {
          "step": 1,
          "done": true,
          "status": "pending",
          "title": "Payment Initiated",
          "description": "Customer opened payment link"
        },
        {
          "step": 2,
          "done": true,
          "status": "completed",
          "title": "Payment Completed",
          "description": "Funds received and converted"
        }
      ]
    },
    "updated_at": "2025-12-09T10:15:45.123456Z"
  }
}

​
payment_request.expired

Sent when: Payment link expires without being completed (typically after 30 minutes to 1 hour). Use case: Update order status to “Payment Expired”, send a new payment link to customer, or cancel the pending order. 
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "payment_request.expired",
  "data": {
    "id": "PAYR_ExpiredLink123",
    "additional_info": {
      "email": "[email protected]",
      "name": "Jane Smith",
      "phone_number": "+2348098765432",
      "source": "invoice"
    },
    "created_at": "2025-12-09T08:00:00.000000Z",
    "expires_at": "2025-12-09T09:00:00.000000Z",
    "expired_at": "2025-12-09T09:00:00.123456Z",
    "fees": [],
    "merchant_info": {
      "email": "[email protected]",
      "name": "Liverpool"
    },
    "reference": "PAYR_ExpiredLink123",
    "source": "payment_link",
    "source_amount": "16.91200347",
    "source_id": "LINK_abc123",
    "status": "expired",
    "target_amount": "25000",
    "source_currency": "USDT",
    "target_currency": "NGN",
    "rate": {
      "product": "USDTNGN",
      "rate": "1478.50",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "USDT",
      "target_currency": "NGN"
    },
    "timeline": {
      "total_steps": 0,
      "current_step": 0,
      "transfer_status": "",
      "events": []
    },
    "updated_at": "2025-12-09T09:00:00.123456Z"
  }
}

​
payment_request.cancelled

Sent when: Payment request is manually cancelled by merchant or customer before completion. Use case: Clean up pending orders, update inventory, refund if partial payment was made, or notify customer of cancellation. 
{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "payment_request.cancelled",
  "data": {
    "id": "PAYR_Cancelled456",
    "additional_info": {
      "email": "[email protected]",
      "name": "Michael Johnson",
      "phone_number": "+2347012345678",
      "source": "email_invoice"
    },
    "created_at": "2025-12-09T07:30:00.000000Z",
    "cancelled_at": "2025-12-09T08:15:00.123456Z",
    "cancellation_reason": "Customer requested cancellation",
    "fees": [],
    "merchant_info": {
      "email": "[email protected]",
      "name": "Liverpool"
    },
    "reference": "PAYR_Cancelled456",
    "source": "payment_link",
    "source_amount": "0.00033",
    "source_id": "INV_2025_001",
    "status": "cancelled",
    "target_amount": "50000",
    "source_currency": "BTC",
    "target_currency": "NGN",
    "rate": {
      "product": "BTCNGN",
      "rate": "151515151.52",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "BTC",
      "target_currency": "NGN"
    },
    "timeline": {
      "total_steps": 0,
      "current_step": 0,
      "transfer_status": "",
      "events": []
    },
    "updated_at": "2025-12-09T08:15:00.123456Z"
  }
}

​
Setting Up Webhooks

To configure webhooks in your Busha account and implement webhook handlers, see our Webhooks Setup Guide for detailed instructions.

​
Testing Webhooks

​
Using webhook.site

  1. Go to webhook.site
  2. Copy your unique URL
  3. Add it to your Busha webhook settings
  4. Create a test transaction in sandbox mode
  5. View the webhook payload in real-time on webhook.site

​
Troubleshooting

​
Webhooks Not Being Received

  1. Check your webhook URL is accessible from the internet
  2. Verify your endpoint returns 200 status code

​
What’s next?