Webhook Events Reference

Complete reference of all webhook events and their payload schemas.

This page documents every webhook event IvoryPay can send, along with the exact payload schema for each.

Payload envelope

All webhook payloads follow this structure:

{
  "event": "event.name",
  "data": { ... }
}

---

On-Ramp Events

onramp.success

Fired when an on-ramp transaction completes successfully — crypto has been delivered to the user's wallet.

{
  "event": "onramp.success",
  "data": {
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 31.25,
    "platformFeeInCrypto": 0.15,
    "businessFeeInCrypto": 0,
    "gasFee": 0.5,
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68",
    "network": "BSC_MAINNET",
    "token": "USDT",
    "transactionHash": "0xabc123...",
    "status": "SUCCESS",
    "customer": {
      "refCode": "abc123def4",
      "email": "[e-mail]",
      "userId": "user-uuid",
      "firstName": "Amina",
      "lastName": "Okafor",
      "context": "LIVE",
      "createdAtDateOnly": "2026-03-26",
      "createdAt": "2026-03-26T12:00:00.000Z"
    }
  }
}

Field	Type	Description
reference	string	Your transaction reference
amount	number	Crypto amount delivered
platformFeeInCrypto	number	IvoryPay platform fee in crypto
businessFeeInCrypto	number	Your business fee in crypto
gasFee	number	Blockchain gas fee
walletAddress	string	Destination wallet
network	string	Blockchain network
token	string	Crypto token
transactionHash	string	On-chain transaction hash
status	string	Transaction status
customer	object	Customer details

---

onramp.fiatPaymentReceived

Fired when the user's fiat payment has been detected and confirmed.

{
  "event": "onramp.fiatPaymentReceived",
  "data": {
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "accountNumber": "1234567890",
    "status": "FIAT_PAYMENT_RECEIVED",
    "currency": "NGN",
    "accountName": "IvoryPay - Amina Okafor",
    "bank": "Providus Bank",
    "receivedAmount": 50000,
    "settledAmount": 49750,
    "customer": { ... }
  }
}

---

onramp.cryptoPayoutProcessing

Fired when the crypto payout is being processed (sent on-chain).

---

onramp.failed

Fired when an on-ramp transaction fails.

{
  "event": "onramp.failed",
  "data": {
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 31.25,
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68",
    "status": "FAILED",
    "failedReason": "Insufficient liquidity",
    "network": "BSC_MAINNET",
    "token": "USDT",
    "customer": { ... }
  }
}

---

Off-Ramp Events

offramp.success

Fired when fiat has been successfully paid out to the user's bank account.

{
  "event": "offramp.success",
  "data": {
    "reference": "660e8400-e29b-41d4-a716-446655440001",
    "status": "SUCCESS",
    "accountName": "NWANKWO CHIDI",
    "accountNumber": "0123456789",
    "bankName": "GTBank",
    "currency": "NGN",
    "amount": 100000,
    "transactionHash": "0xdef456...",
    "customer": { ... }
  }
}

---

offramp.cryptoPaymentReceived

Fired when the user's crypto deposit has been detected on-chain.

{
  "event": "offramp.cryptoPaymentReceived",
  "data": {
    "reference": "660e8400-e29b-41d4-a716-446655440001",
    "status": "CRYPTO_PAYMENT_RECEIVED",
    "token": "USDT",
    "network": "BSC_MAINNET",
    "transactionHash": "0xdef456...",
    "amount": 62.5,
    "customer": { ... }
  }
}

---

offramp.failed

Fired when an off-ramp transaction fails.

{
  "event": "offramp.failed",
  "data": {
    "reference": "660e8400-e29b-41d4-a716-446655440001",
    "status": "FAILED",
    "token": "USDT",
    "network": "BSC_MAINNET",
    "amount": 62.5,
    "failedReason": "Bank transfer failed",
    "customer": { ... }
  }
}

---

offramp.declined

Fired when an off-ramp transaction is declined (e.g., compliance check failure).

{
  "event": "offramp.declined",
  "data": {
    "reference": "660e8400-e29b-41d4-a716-446655440001",
    "status": "DECLINED",
    "token": "USDT",
    "network": "BSC_MAINNET",
    "amount": 62.5,
    "reasonForDecline": "Transaction flagged by compliance",
    "customer": { ... }
  }
}

---

Buy Events

buy.success

Fired when a Buy (fiat collection) transaction completes.

{
  "event": "buy.success",
  "data": {
    "reference": "770e8400-e29b-41d4-a716-446655440002",
    "status": "SUCCESS",
    "accountNumber": "9876543210",
    "currency": "NGN",
    "accountName": "IvoryPay - Kemi Adeyemi",
    "bankName": "Providus Bank",
    "amount": 25000,
    "customer": { ... }
  }
}

buy.failed

Fired when a Buy transaction fails.

buy.mismatch

Fired when the amount received differs from the expected amount.

---

Sell Events

sell.success

Fired when a Sell (fiat payout) transaction completes.

{
  "event": "sell.success",
  "data": {
    "reference": "880e8400-e29b-41d4-a716-446655440003",
    "status": "SUCCESS",
    "accountName": "Tunde Bakare",
    "accountNumber": "0123456789",
    "bankName": "GTBank",
    "currency": "NGN",
    "amount": 75000,
    "customer": { ... }
  }
}

sell.failed

Fired when a Sell payout fails.

sell.cancelled

Fired when a Sell payout is cancelled.

---

Deposit Events

deposit.received

Fired when fiat is deposited into a virtual account.

{
  "event": "deposit.received",
  "data": {
    "reference": "dep_abc123",
    "processorReference": "prov_xyz789",
    "accountNumber": "9900123456",
    "accountName": "IvoryPay - User Name",
    "currency": "NGN",
    "receivedAmount": 100000,
    "settledAmount": 99500,
    "status": "SUCCESS",
    "sourceAccountNumber": "0987654321",
    "sourceAccountName": "Sender Name",
    "sourceBankName": "GTBank",
    "paymentDate": "2026-03-26T14:30:00.000Z"
  }
}

Field	Type	Description
reference	string	Deposit reference
processorReference	string	Payment processor's reference
accountNumber	string	Virtual account that received the deposit
receivedAmount	number	Gross amount received
settledAmount	number	Net amount after processor fees
sourceAccountNumber	string	Sender's bank account
sourceAccountName	string	Sender's account name
sourceBankName	string	Sender's bank
paymentDate	string	ISO 8601 payment timestamp

---

Settlement Events

settlement.awaitingSettlementAccount

Settlement waiting for account configuration.

settlement.converting

Fiat-to-crypto conversion in progress.

settlement.payoutInitiated

Crypto payout queued.

settlement.payoutProcessing

Crypto being sent on-chain.

settlement.success

Settlement completed — crypto delivered.

{
  "event": "settlement.success",
  "data": {
    "reference": "set_abc123",
    "settlementId": "set-uuid-1",
    "depositId": "dep-uuid-1",
    "fiatAmount": 99500,
    "fiatCurrency": "NGN",
    "cryptoAmount": 62.18,
    "token": "USDT",
    "chain": "BSC_MAINNET",
    "destinationAddress": "0xYourWallet...",
    "conversionRate": 1600,
    "platformFee": 0.31,
    "businessFee": 0,
    "gasFee": 0.5,
    "cryptoPayoutReference": "payout_ref_123",
    "transactionHash": "0xsettlement123...",
    "status": "COMPLETED"
  }
}

settlement.failed

Settlement failed — check failureReason.

{
  "event": "settlement.failed",
  "data": {
    "reference": "set_abc123",
    "settlementId": "set-uuid-1",
    "depositId": "dep-uuid-1",
    "fiatAmount": 99500,
    "fiatCurrency": "NGN",
    "status": "FAILED",
    "failureReason": "Insufficient crypto liquidity"
  }
}

---

Customer object (shared across events)

The customer object appears in on-ramp, off-ramp, buy, and sell webhook payloads:

{
  "refCode": "abc123def4",
  "email": "[e-mail]",
  "userId": "user-uuid",
  "firstName": "Amina",
  "lastName": "Okafor",
  "context": "LIVE",
  "createdAtDateOnly": "2026-03-26",
  "createdAt": "2026-03-26T12:00:00.000Z"
}

Field	Type	Description
refCode	string	IvoryPay customer reference
email	string	Customer's email
userId	string	Business user ID
firstName	string	Customer's first name
lastName	string	Customer's last name
context	string	TEST or LIVE
createdAtDateOnly	string	Date customer was created
createdAt	string	Full ISO 8601 timestamp