> ## Documentation Index
> Fetch the complete documentation index at: https://docs.busha.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Events

> Real-time notifications for transfers, deposits, conversions, payouts, payment requests, and customer verification in your Busha integration.

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.

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### customer.updated

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### customer.verification.in\_review

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### customer.verification.active

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### customer.verification.rejected

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### customer.verification.inactive

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### transfer.processing

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### transfer.funds\_received

**Sent when:** Funds have been successfully received into your Busha account. This is an intermediate status before conversion.

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### transfer.completed

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### transfer.failed

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### transfer.cancelled

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### 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).

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### transfer.funds\_refunded

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### transfer.funds\_delivered

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### payment\_request.processing

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### payment\_request.completed

**Sent when:** Customer successfully completes payment via payment link.

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### payment\_request.expired

**Sent when:** Payment link expires without being completed.

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### payment\_request.failed

**Sent when:** Payment request fails due to an error.

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### payment\_request.cancelled

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### ramp.transfer.completed

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

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

### ramp.transfer.failed

**Sent when:** Ramp transfer fails due to an error.

<Accordion title="View sample event">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

***

## Setting Up Webhooks

To configure webhooks in your Busha account and implement webhook handlers, see our [Webhooks Setup Guide](/guides/webhooks/setup) for detailed instructions.

## See Also

* [Verify Customer Identity](/guides/customers/verify-identity) - Learn about customer verification flow
* [Create Individual Customer](/guides/customers/create-individual) - Set up individual customers
* [Create Business Customer](/guides/customers/create-business) - Set up business customers

***