Webhook Events • Busha Developer Documentation

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
Automate customer verification workflows

Customer Events

Customer events track the lifecycle of customer accounts, including creation, updates, and verification status changes.

customer.created

Sent when: A new customer account is created.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "customer.created",
  "data": {
    "id": "CUS_Ikdb49NLsnlYU",
    "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "business_name": "",
    "first_name": "John",
    "last_name": "Doe",
    "email": "customer@gmail.com",
    "type": "individual",
    "status": "inactive",
    "level": "0",
    "created_at": "2026-01-27T09:23:09.317273Z"
  }
}

customer.updated

Sent when: Customer account information is updated (e.g., address, phone number, documents).

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "customer.updated",
  "data": {
    "id": "CUS_Ikdb49NLsnlYU",
    "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "first_name": "John",
    "last_name": "Doe",
    "email": "customer@gmail.com",
    "phone": "+234 8087654321",
    "type": "individual",
    "status": "inactive",
    "level": "0",
    "created_at": "2026-01-27T09:23:09.317273Z",
    "updated_at": "2026-01-27T09:25:15.123456Z"
  }
}

customer.verification.in_review

Sent when: Customer verification documents have been submitted and are under review.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "customer.verification.in_review",
  "data": {
    "id": "CUS_Ikdb49NLsnlYU",
    "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "business_name": "",
    "first_name": "John",
    "last_name": "Doe",
    "email": "customer@gmail.com",
    "type": "individual",
    "status": "in_review",
    "level": "0",
    "created_at": "2026-01-27T09:23:09.317273Z",
    "updated_at": "2026-01-27T09:26:34.537881Z"
  }
}

customer.verification.active

Sent when: Customer verification has been approved and the account is now active.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "customer.verification.active",
  "data": {
    "id": "CUS_Ikdb49NLsnlYU",
    "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "business_name": "",
    "first_name": "John",
    "last_name": "Doe",
    "email": "customer@gmail.com",
    "type": "individual",
    "status": "active",
    "level": "1",
    "created_at": "2026-01-27T09:23:09.317273Z",
    "updated_at": "2026-01-27T10:15:20.456789Z"
  }
}

customer.verification.rejected

Sent when: Customer verification has been rejected due to invalid or incomplete documents.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "customer.verification.rejected",
  "data": {
    "id": "CUS_Ikdb49NLsnlYU",
    "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "business_name": "",
    "first_name": "John",
    "last_name": "Doe",
    "email": "customer@gmail.com",
    "type": "individual",
    "status": "rejected",
    "level": "0",
    "rejection_reason": "Invalid identification documents provided",
    "created_at": "2026-01-27T09:23:09.317273Z",
    "updated_at": "2026-01-27T10:30:45.789012Z"
  }
}

customer.verification.inactive

Sent when: Customer verification status has been reverted to inactive (e.g., due to compliance issues or account suspension).

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "customer.verification.inactive",
  "data": {
    "id": "CUS_Ikdb49NLsnlYU",
    "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "business_name": "",
    "first_name": "John",
    "last_name": "Doe",
    "email": "customer@gmail.com",
    "type": "individual",
    "status": "inactive",
    "level": "0",
    "created_at": "2026-01-27T09:23:09.317273Z",
    "updated_at": "2026-01-27T11:00:00.123456Z"
  }
}

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.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "transfer.pending",
  "data": {
    "id": "TRF_HGjjAUDo1pti",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "quote_id": "QUO_0qoz7fXtHRFd",
    "description": "Sold BTC",
    "sub_description": "For NGN",
    "source_currency": "BTC",
    "target_currency": "NGN",
    "source_amount": "0.00036606",
    "target_amount": "50001.27",
    "trade": "sell",
    "rate": {
      "product": "BTCNGN",
      "rate": "136593125.15",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "BTC",
      "target_currency": "NGN"
    },
    "fees": [],
    "pay_in": {
      "address": "tb1qnltjz527u6pxvcavqwrrja6znyrgd9c2pcl7qu",
      "expires_at": "2025-12-10T11:35:59.175239Z",
      "network": "BTC",
      "type": "address"
    },
    "status": "pending",
    "timeline": {
      "total_steps": 0,
      "current_step": 0,
      "transfer_status": "",
      "events": []
    },
    "created_at": "2025-12-10T10:35:59.108130515Z",
    "updated_at": "2025-12-10T10:35:59.108130584Z"
  }
}

transfer.processing

Sent when: Funds have been received and are being actively processed.

View sample event

{
  "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. This is an intermediate status before conversion.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "transfer.funds_received",
  "data": {
    "id": "TRF_5Vel81eg7kuz",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "quote_id": "QUO_K7viFhMDuYE4",
    "description": "Bought BTC",
    "sub_description": "With USDT",
    "source_currency": "USDT",
    "target_currency": "BTC",
    "source_amount": "16.80378556",
    "target_amount": "0.00018",
    "trade": "buy",
    "rate": {
      "product": "BTCUSDT",
      "rate": "90825.65",
      "side": "buy",
      "type": "FIXED",
      "source_currency": "USDT",
      "target_currency": "BTC"
    },
    "fees": [],
    "pay_in": {
      "address": "0x28730e094b58cb4e8B57549fC451aaB3423Ba4B7",
      "expires_at": "2025-12-05T14:31:33.610518Z",
      "network": "BSC",
      "type": "address",
      "blockchain_hash": "busha_579b948e43caf0f89c4edfc4572425a38564ac708b9bfba177bd395d49076c53",
      "blockchain_url": "https://testnet-explorer.binance.org/tx/busha_579b948e43caf0f89c4edfc4572425a38564ac708b9bfba177bd395d49076c53",
      "from_address": "busha/groot/USDT/PYT_FpqPiXPvLa6T"
    },
    "status": "funds_received",
    "timeline": {
      "total_steps": 0,
      "current_step": 0,
      "transfer_status": "",
      "events": []
    },
    "created_at": "2025-12-05T13:31:33.537625Z",
    "updated_at": "2025-12-05T13:32:42.685331Z"
  }
}

transfer.funds_converted

Sent when: Currency conversion is complete (crypto-to-fiat, fiat-to-crypto, or crypto-to-crypto). This is the final status for conversion transfers.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "transfer.funds_converted",
  "data": {
    "id": "TRF_5Vel81eg7kuz",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "quote_id": "QUO_K7viFhMDuYE4",
    "description": "Bought BTC",
    "sub_description": "With USDT",
    "source_currency": "USDT",
    "target_currency": "BTC",
    "source_amount": "16.80378556",
    "target_amount": "0.00018",
    "trade": "buy",
    "rate": {
      "product": "BTCUSDT",
      "rate": "90825.65",
      "side": "buy",
      "type": "FIXED",
      "source_currency": "USDT",
      "target_currency": "BTC"
    },
    "fees": [],
    "pay_in": {
      "address": "0x28730e094b58cb4e8B57549fC451aaB3423Ba4B7",
      "expires_at": "2025-12-05T14:31:33.610518Z",
      "network": "BSC",
      "type": "address",
      "blockchain_hash": "busha_579b948e43caf0f89c4edfc4572425a38564ac708b9bfba177bd395d49076c53",
      "blockchain_url": "https://testnet-explorer.binance.org/tx/busha_579b948e43caf0f89c4edfc4572425a38564ac708b9bfba177bd395d49076c53",
      "from_address": "busha/groot/USDT/PYT_FpqPiXPvLa6T"
    },
    "status": "funds_converted",
    "timeline": {
      "total_steps": 0,
      "current_step": 0,
      "transfer_status": "",
      "events": []
    },
    "created_at": "2025-12-05T13:31:33.537625Z",
    "updated_at": "2025-12-05T13:32:42.836738Z"
  }
}

transfer.completed

Sent when: Transfer has been successfully completed. This is the final status for successful transfers.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "transfer.completed",
  "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": "completed",
    "timeline": {
      "total_steps": 2,
      "current_step": 2,
      "transfer_status": "completed",
      "events": [
        {
          "step": 1,
          "done": true,
          "status": "funds_received",
          "title": "Crypto Received",
          "description": "Funded from Balance"
        },
        {
          "step": 2,
          "done": true,
          "status": "completed",
          "title": "Transfer Completed",
          "description": "Funds have been successfully processed"
        }
      ]
    },
    "created_at": "2025-12-05T13:12:57.582284Z",
    "updated_at": "2025-12-05T13:14:38.243849Z"
  }
}

transfer.failed

Sent when: Transfer fails due to an error (insufficient funds, network issues, invalid recipient details, etc.).

View sample event

{
  "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"
  }
}

transfer.cancelled

Sent when: Transfer is cancelled (due to user cancellation or system cancellation).

View sample event

{
  "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.funds_not_delivered

Sent when: Funds were received but could not be delivered to the final destination (e.g., invalid bank account, network issues during payout).

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "transfer.funds_not_delivered",
  "data": {
    "id": "TRF_notDelivered789",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "source_currency": "NGN",
    "target_currency": "NGN",
    "source_amount": "5000",
    "target_amount": "5000",
    "status": "funds_not_delivered",
    "pay_out": {
      "type": "bank_transfer",
      "recipient_details": {
        "account_name": "John Doe",
        "account_number": "0123456789",
        "bank_name": "First Bank of Nigeria"
      }
    },
    "error": {
      "code": "invalid_account",
      "message": "Bank account details are invalid or account is closed"
    },
    "created_at": "2025-12-05T14:20:00.000000Z",
    "updated_at": "2025-12-05T14:25:00.000000Z"
  }
}

transfer.funds_refunded

Sent when: Funds are refunded to the balance following a failed transfer.

View sample event

{
  "business_id": "BUS_5XUsDLKxHTapLHMhlMmcM",
  "event": "transfer.funds_refunded",
  "data": {
    "id": "TRF_X0YjV4Z36JW3",
    "profile_id": "BUS_5XUsDLKxHTapLHMhlMmcM",
    "quote_id": "QUO_9sxWKHbsJEJ2",
    "description": "Sold BTC",
    "sub_description": "For BTC",
    "source_currency": "BTC",
    "target_currency": "BTC",
    "source_amount": "0.000075",
    "target_amount": "0.00007",
    "rate": {
      "rate": "1",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "BTC",
      "target_currency": "BTC"
    },
    "fees": [
      {
        "amount": {
          "amount": "0.000005",
          "currency": "BTC"
        },
        "name": "network fee",
        "type": "FIXED"
      }
    ],
    "pay_out": {
      "address": "tb1ql8xvg2adnt0j5vxzgg7n00zmaf4y65wegpvzcl",
      "network": "BTC",
      "type": "address"
    },
    "status": "funds_refunded",
    "timeline": {
      "total_steps": 0,
      "current_step": 0,
      "transfer_status": "",
      "events": []
    },
    "created_at": "2026-02-03T15:01:20.239458Z",
    "updated_at": "2026-02-03T15:07:36.608114Z"
  }
}

transfer.funds_delivered

Sent when: Funds have been successfully delivered to the final destination (e.g., bank account or external wallet).

View sample event

{
  "business_id": "BUS_5asfnvrY9UuXBun4GWqNW",
  "event": "transfer.funds_delivered",
  "data": {
    "id": "TRF_BuIVXa89aFC3",
    "profile_id": "BUS_5asfnvrY9UuXBun4GWqNW",
    "quote_id": "QUO_VJOBEK5ycGVM",
    "stages": [
      "conversion",
      "withdrawal"
    ],
    "category": "sell",
    "description": "Sold USDC",
    "sub_description": "For NGN",
    "source_currency": "USDC",
    "target_currency": "NGN",
    "source_amount": "0.4430943",
    "target_amount": "500",
    "trade": "sell",
    "rate": {
      "product": "USDCNGN",
      "rate": "1371.04",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "USDC",
      "target_currency": "NGN"
    },
    "fees": [
      {
        "amount": {
          "amount": "100",
          "currency": "NGN"
        },
        "name": "Fees",
        "type": "FIXED"
      },
      {
        "amount": {
          "amount": "7.5",
          "currency": "NGN"
        },
        "name": "VAT on Fee (7.5%)",
        "type": "FIXED"
      }
    ],
    "pay_out": {
      "recipient_details": {
        "account_name": "ABDULAZEEZ  ABDULAZEEZ ADESHIN",
        "account_number": "0453699151",
        "bank_code": "000013",
        "bank_name": "Guaranty Trust Bank"
      },
      "recipient_id": "68cbd12c0dd5c496d6fcb181",
      "type": "bank_transfer",
      "session_id": "090405260508143512664405513864"
    },
    "status": "funds_delivered",
    "timeline": {
      "total_steps": 0,
      "current_step": 0,
      "transfer_status": "",
      "events": []
    },
    "created_at": "2026-05-08T13:33:52.23489Z",
    "updated_at": "2026-05-08T13:35:14.54597Z"
  }
}

Deposit Events

Deposit events track incoming funds to your Busha account from fiat or crypto sources.

deposit.success

Sent when: Funds are successfully deposited to your Busha account (fiat via bank transfer or crypto via wallet). Use case: Automatically convert deposits to your preferred currency using the Quotes and Transfers endpoints. For example, convert incoming fiat deposits to stablecoin or vice versa.

View sample event

{
  "business_id": "bus_1a2b3c4d5e6f7g8h9i0j",
  "event": "deposit.success",
  "data": {
    "id": "289bb2c1-b4fc-46df-b313-6945a8d23615",
    "profile_id": "CUS_9z8y7x6w5v4u3t2s1r",
    "amount": "5900.00",
    "fee": "100.00",
    "total": "6000.00",
    "currency": "NGN",
    "reference": "Resf12dx3c333333",
    "channel": "bank_transfer",
    "status": "COMPLETED",
    "source_account_name": "Test Oluwatoni",
    "source_bank_name": "Bank of World",
    "source_account_number": "1234567890",
    "reserved_account_id": "8d1c58b0-9143-410b-be61-805e8421c466",
    "account_name": "ARTAX DIGITAL / Oluwatoni Test",
    "account_number": "4051483002",
    "created_at": "2025-02-26T11:29:02.336285+01:00"
  }
}

Key fields:

amount: The deposited amount (after fees)
fee: The deposit fee charged
total: The total amount deposited (before fees)
currency: The currency of the deposit (e.g., NGN, KES)
status: Deposit status (COMPLETED)
profile_id: The customer ID who made the deposit
reference: Unique deposit reference for reconciliation
channel: The method of deposit (e.g., bank_transfer)

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.pending

Sent when: Payment request is awaiting customer payment.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "payment_request.pending",
  "data": {
    "id": "PAYR_oIPbFOXogbjW",
    "additional_info": {
      "email": "ajibola@busha.co",
      "name": "Jibola Obi",
      "phone_number": "",
      "source": ""
    },
    "created_at": "2025-12-10T10:35:59.220244444Z",
    "expires_at": "2025-12-10T11:35:59.175239Z",
    "fees": [],
    "merchant_info": {
      "email": "ajibola@busha.co",
      "name": "Liverppol"
    },
    "pay_in": {
      "address": "tb1qnltjz527u6pxvcavqwrrja6znyrgd9c2pcl7qu",
      "expires_at": "2025-12-10T11:35:59.175239Z",
      "network": "BTC",
      "type": "address"
    },
    "rate": {
      "product": "BTCNGN",
      "rate": "136593125.15",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "BTC",
      "target_currency": "NGN"
    },
    "reference": "PAYR_oIPbFOXogbjW",
    "source_amount": "0.00036606",
    "status": "pending",
    "target_amount": "50001.27",
    "timeline": {
      "total_steps": 0,
      "current_step": 0,
      "transfer_status": "",
      "events": []
    },
    "updated_at": "2025-12-10T10:35:59.220244497Z",
    "source_currency": "BTC",
    "target_currency": "NGN"
  }
}

payment_request.processing

Sent when: Payment has been received and is being processed.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "payment_request.processing",
  "data": {
    "id": "PAYR_NwSBgvVszPvA",
    "additional_info": {
      "email": "ajibola@busha.co",
      "name": "Jibola Obi",
      "phone_number": "+2348012345678",
      "source": "checkout_page"
    },
    "created_at": "2025-12-09T09:51:03.422936437Z",
    "merchant_info": {
      "email": "ajibola@busha.co",
      "name": "Liverpool"
    },
    "pay_in": {
      "address": "GDHHXPUSZK2OYHEVAP7GG6MTDWY2VQ4V5JBTIKFEV526RT6QYF23BSXD",
      "network": "XLM",
      "type": "address",
      "blockchain_hash": "abc123def456...",
      "blockchain_url": "https://stellarchain.io/tx/abc123def456..."
    },
    "reference": "PAYR_NwSBgvVszPvA",
    "source": "payment_link",
    "source_amount": "6.76480139",
    "source_id": "58HgbtNDA34Z",
    "status": "processing",
    "target_amount": "10000",
    "source_currency": "USDC",
    "target_currency": "NGN",
    "updated_at": "2025-12-09T10:10:30.123456Z"
  }
}

payment_request.completed

Sent when: Customer successfully completes payment via payment link.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "payment_request.completed",
  "data": {
    "id": "PAYR_InpIYLNIivEr",
    "additional_info": {
      "email": "ajibola@busha.co",
      "name": "Jibola Obiwole",
      "phone_number": "",
      "source": ""
    },
    "created_at": "2025-12-05T13:28:02.698909Z",
    "expires_at": "2025-12-05T14:28:02.611403Z",
    "fees": [],
    "merchant_info": {
      "email": "ajibola@busha.co",
      "name": "Liverppol"
    },
    "pay_in": {
      "address": "0x817e43857CBFdCf48F2b35E86570031E46D8Db11",
      "expires_at": "2025-12-05T14:28:02.611403Z",
      "network": "BSC",
      "type": "address"
    },
    "rate": {
      "product": "USDTNGN",
      "rate": "1487.76",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "USDT",
      "target_currency": "NGN"
    },
    "reference": "PAYR_InpIYLNIivEr",
    "source_amount": "16.80378556",
    "status": "completed",
    "target_amount": "25000",
    "timeline": {
      "total_steps": 3,
      "current_step": 3,
      "transfer_status": "funds_converted",
      "events": [
        {
          "step": 1,
          "done": true,
          "status": "pending",
          "title": "Transfer Started",
          "description": "Waiting for your USDT deposit",
          "timestamp": "2025-12-05T13:29:00.723079Z"
        },
        {
          "step": 2,
          "done": true,
          "status": "funds_received",
          "title": "Crypto Received",
          "description": "We received your USDT Deposit",
          "timestamp": "2025-12-05T13:29:00.723079Z"
        },
        {
          "step": 3,
          "done": true,
          "status": "funds_converted",
          "title": "Funds Converted",
          "description": "Money has been added to your wallet.",
          "timestamp": "2025-12-05T13:29:00.853277Z"
        }
      ]
    },
    "updated_at": "2025-12-05T13:29:01.974712Z",
    "source_currency": "USDT",
    "target_currency": "NGN"
  }
}

payment_request.expired

Sent when: Payment link expires without being completed.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "payment_request.expired",
  "data": {
    "id": "PAYR_oIPbFOXogbjW",
    "additional_info": {
      "email": "ajibola@busha.co",
      "name": "Jibola Obi",
      "phone_number": "",
      "source": ""
    },
    "created_at": "2025-12-10T10:35:59.220244Z",
    "expires_at": "2025-12-10T11:35:59.175239Z",
    "fees": [],
    "merchant_info": {
      "email": "ajibola@busha.co",
      "name": "Liverppol"
    },
    "pay_in": {
      "address": "tb1qnltjz527u6pxvcavqwrrja6znyrgd9c2pcl7qu",
      "expires_at": "2025-12-10T11:35:59.175239Z",
      "network": "BTC",
      "type": "address"
    },
    "rate": {
      "product": "BTCNGN",
      "rate": "136593125.15",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "BTC",
      "target_currency": "NGN"
    },
    "reference": "PAYR_oIPbFOXogbjW",
    "source_amount": "0.00036606",
    "status": "expired",
    "target_amount": "50001.27",
    "timeline": {
      "total_steps": 1,
      "current_step": 1,
      "transfer_status": "cancelled",
      "events": [
        {
          "step": 1,
          "done": true,
          "status": "pending",
          "title": "Transfer Started",
          "description": "Waiting for your BTC deposit",
          "timestamp": "2025-12-10T11:36:00.281594Z"
        }
      ]
    },
    "updated_at": "2025-12-10T12:30:51.466553Z",
    "source_currency": "BTC",
    "target_currency": "NGN"
  }
}

payment_request.failed

Sent when: Payment request fails due to an error.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "payment_request.failed",
  "data": {
    "id": "PAYR_failed456",
    "additional_info": {
      "email": "customer@example.com",
      "name": "Jane Smith",
      "phone_number": "+2348098765432",
      "source": "checkout"
    },
    "created_at": "2025-12-09T08:00:00.000000Z",
    "fees": [],
    "merchant_info": {
      "email": "merchant@busha.co",
      "name": "Liverpool"
    },
    "reference": "PAYR_failed456",
    "source": "payment_link",
    "source_amount": "16.91200347",
    "source_id": "ORDER_789",
    "status": "failed",
    "target_amount": "25000",
    "source_currency": "USDT",
    "target_currency": "NGN",
    "error": {
      "code": "insufficient_funds",
      "message": "Customer sent insufficient funds to complete payment"
    },
    "updated_at": "2025-12-09T08:30:00.123456Z"
  }
}

payment_request.cancelled

Sent when: Payment request is manually cancelled by merchant or customer before completion.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "payment_request.cancelled",
  "data": {
    "id": "PAYR_Cancelled456",
    "additional_info": {
      "email": "customer@example.com",
      "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": "merchant@busha.co",
      "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"
  }
}

Ramp Events

Ramp events track on/off-ramp transactions where users convert between fiat and cryptocurrency through Busha’s ramp service.

ramp.transfer.pending

Sent when: A ramp transfer (fiat to crypto or crypto to fiat) has been initiated and is awaiting processing.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "ramp.transfer.pending",
  "data": {
    "id": "RAMP_TRF_abc123",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "ramp_type": "on_ramp",
    "source_currency": "NGN",
    "target_currency": "USDT",
    "source_amount": "50000",
    "target_amount": "33.78",
    "status": "pending",
    "rate": {
      "product": "NGNUSDT",
      "rate": "1480.00",
      "side": "buy",
      "type": "FIXED"
    },
    "created_at": "2025-12-09T12:00:00.000000Z"
  }
}

ramp.transfer.completed

Sent when: Ramp transfer has been successfully completed and funds have been delivered.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "ramp.transfer.completed",
  "data": {
    "id": "RAMP_TRF_abc123",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "ramp_type": "on_ramp",
    "source_currency": "NGN",
    "target_currency": "USDT",
    "source_amount": "50000",
    "target_amount": "33.78",
    "status": "completed",
    "rate": {
      "product": "NGNUSDT",
      "rate": "1480.00",
      "side": "buy",
      "type": "FIXED"
    },
    "created_at": "2025-12-09T12:00:00.000000Z",
    "completed_at": "2025-12-09T12:05:30.123456Z"
  }
}

ramp.transfer.failed

Sent when: Ramp transfer fails due to an error.

View sample event

{
  "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
  "event": "ramp.transfer.failed",
  "data": {
    "id": "RAMP_TRF_failed789",
    "profile_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
    "ramp_type": "off_ramp",
    "source_currency": "BTC",
    "target_currency": "NGN",
    "source_amount": "0.001",
    "target_amount": "135796.71",
    "status": "failed",
    "error": {
      "code": "bank_account_invalid",
      "message": "Recipient bank account details are invalid"
    },
    "created_at": "2025-12-09T12:00:00.000000Z",
    "failed_at": "2025-12-09T12:03:00.123456Z"
  }
}

Setting Up Webhooks

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

​Why Use Webhooks?

​Customer Events

​customer.created

​customer.updated

​customer.verification.in_review

​customer.verification.active

​customer.verification.rejected

​customer.verification.inactive

​Transfer Events

​transfer.pending

​transfer.processing

​transfer.funds_received

​transfer.funds_converted

​transfer.completed

​transfer.failed

​transfer.cancelled

​transfer.funds_not_delivered

​transfer.funds_refunded

​transfer.funds_delivered

​Deposit Events

​deposit.success

​Payment Request Events

​payment_request.pending

​payment_request.processing

​payment_request.completed

​payment_request.expired

​payment_request.failed

​payment_request.cancelled

​Ramp Events

​ramp.transfer.pending

​ramp.transfer.completed

​ramp.transfer.failed

​Setting Up Webhooks

​See Also

Why Use Webhooks?

Customer Events

customer.created

customer.updated

customer.verification.in_review

customer.verification.active

customer.verification.rejected

customer.verification.inactive

Transfer Events

transfer.pending

transfer.processing

transfer.funds_received

transfer.funds_converted

transfer.completed

transfer.failed

transfer.cancelled

transfer.funds_not_delivered

transfer.funds_refunded

transfer.funds_delivered

Deposit Events

deposit.success

Payment Request Events

payment_request.pending

payment_request.processing

payment_request.completed

payment_request.expired

payment_request.failed

payment_request.cancelled

Ramp Events

ramp.transfer.pending

ramp.transfer.completed

ramp.transfer.failed

Setting Up Webhooks

See Also