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": "amina@example.com",
      "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).

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

Field

Type

Description

reference

string

Your transaction reference

amount

number

Crypto amount to be delivered

network

string

Blockchain network

token

string

Crypto token

status

string

Transaction status

walletAddress

string

Destination wallet

customer

object

Customer details

`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": { ... }
  }
}

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

All settlement payloads include a reference field copied from the joined deposit (deposit.reference) — the settlement entity itself has no reference column.

`settlement.awaitingSettlementAccount`

Settlement waiting for account configuration.

{
  "event": "settlement.awaitingSettlementAccount",
  "data": {
    "reference": "dep_abc123",
    "settlementId": "set-uuid-1",
    "depositId": "dep-uuid-1",
    "fiatAmount": 99500,
    "fiatCurrency": "NGN",
    "status": "AWAITING_SETTLEMENT_ACCOUNT",
    "message": "No settlement account configured. Please set up a settlement account to receive your funds."
  }
}

`settlement.converting`

Fiat-to-crypto conversion in progress.

{
  "event": "settlement.converting",
  "data": {
    "reference": "dep_abc123",
    "settlementId": "set-uuid-1",
    "depositId": "dep-uuid-1",
    "fiatAmount": 99500,
    "fiatCurrency": "NGN",
    "status": "CONVERTING"
  }
}

`settlement.payoutInitiated`

Crypto payout queued.

{
  "event": "settlement.payoutInitiated",
  "data": {
    "reference": "dep_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,
    "status": "PAYOUT_INITIATED"
  }
}

`settlement.payoutProcessing`

Crypto being sent on-chain.

{
  "event": "settlement.payoutProcessing",
  "data": {
    "reference": "dep_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",
    "status": "PAYOUT_PROCESSING"
  }
}

`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 and off-ramp webhook payloads:

{
  "refCode": "abc123def4",
  "email": "user@example.com",
  "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

PreviousWebhooks Overview NextWebhook Security

Last updated 2 months ago