Skip to main content

​
Deposit Events

​
deposit.completed

Fired when a deposit is completed successfully.

​
Crypto Deposit

{
  "event": "deposit.completed",
  "event_id": "evt_abc123",
  "timestamp": "2024-01-15T10:30:45Z",
  "data": {
    "transaction_id": "txn_001",
    "customer_id": "cus_123",
    "sender": {
      "address": "0x123...",
      "chain": "Ethereum"
    },
    "recipient": {
      "address": "0x456...",
      "chain": "Ethereum"
    },
    "amount": 1000000,
    "currency": "USDT",
    "reference": "dep-20240115-001",
    "status": "completed",
    "transaction_type": "deposit",
    "blockchain": "Ethereum",
    "transaction_hash": "0x789...",
    "explorer_link": "https://etherscan.io/tx/0x789...",
    "timestamp": "2024-01-15T10:30:40Z"
  }
}

​
Fiat Deposit

{
  "event": "deposit.completed",
  "event_id": "evt_def456",
  "timestamp": "2024-01-15T11:00:00Z",
  "data": {
    "transaction_id": "txn_002",
    "customer_id": "cus_456",
    "sender": {
      "account_name": "John Doe",
      "account_number": "0987654321",
      "bank_name": "GTBank"
    },
    "recipient": {
      "account_name": "Jane Smith",
      "account_number": "0123456789",
      "bank_name": "GTBank"
    },
    "amount": 50000,
    "currency": "NGN",
    "reference": "dep-20240115-002",
    "status": "completed",
    "transaction_type": "deposit",
    "notes": "Bank transfer deposit",
    "timestamp": "2024-01-15T11:00:00Z"
  }
}

​
Withdrawal Events

​
withdrawal.completed

Fired when a withdrawal is completed successfully. 
{
  "event": "withdrawal.completed",
  "event_id": "evt_xyz789",
  "timestamp": "2024-01-15T11:45:23Z",
  "data": {
    "transaction_id": "txn_003",
    "customer_id": "cus_789",
    "recipient": {
      "account_name": "Jane Smith",
      "account_number": "0123456789",
      "bank_name": "GTBank"
    },
    "amount": 25000,
    "currency": "NGN",
    "reference": "wth-20240115-001",
    "status": "completed",
    "transaction_type": "withdrawal",
    "timestamp": "2024-01-15T11:45:20Z"
  }
}

​
Transfer Events

​
transfer.completed

Fired when a transfer is completed successfully. 
{
  "event": "transfer.completed",
  "event_id": "evt_transfer1",
  "timestamp": "2024-01-15T12:30:00Z",
  "data": {
    "transaction_id": "txn_004",
    "customer_id": "cus_123",
    "sender": {
      "address": "0x123...",
      "chain": "Ethereum"
    },
    "recipient": {
      "address": "0x456...",
      "chain": "Ethereum"
    },
    "amount": 500000,
    "currency": "USDT",
    "reference": "trf-20240115-001",
    "status": "completed",
    "transaction_type": "transfer",
    "blockchain": "Ethereum",
    "transaction_hash": "0xabc...",
    "timestamp": "2024-01-15T12:30:00Z"
  }
}

​
transfer.failed

Fired when a transfer fails. 
{
  "event": "transfer.failed",
  "event_id": "evt_transfer2",
  "timestamp": "2024-01-15T13:15:00Z",
  "data": {
    "transaction_id": "txn_005",
    "customer_id": "cus_456",
    "sender": {
      "address": "0x789...",
      "chain": "Ethereum"
    },
    "recipient": {
      "address": "0xabc...",
      "chain": "Ethereum"
    },
    "amount": 300000,
    "currency": "USDT",
    "reference": "trf-20240115-002",
    "status": "failed",
    "transaction_type": "transfer",
    "blockchain": "Ethereum",
    "transaction_hash": "0xdef...",
    "timestamp": "2024-01-15T13:15:00Z"
  }
}

​
Wallet Events

​
wallet.balance.updated

Fired when a wallet balance is updated. 
{
  "event": "wallet.balance.updated",
  "event_id": "evt_balance1",
  "timestamp": "2024-01-15T14:00:00Z",
  "data": {
    "from_account": {
      "id": "acc_001",
      "account_number": "0123456789",
      "account_name": "Main Wallet",
      "bank_name": "GTBank",
      "customer_id": "cus_123"
    },
    "to_account": {
      "id": "acc_002",
      "account_number": "0987654321",
      "account_name": "Savings Wallet",
      "bank_name": "GTBank",
      "customer_id": "cus_123"
    },
    "amount": 25000,
    "currency": "NGN",
    "reference": "bal-20240115-001",
    "narration": "Transfer between accounts",
    "timestamp": "2024-01-15T14:00:00Z"
  }
}

​
Example Handler

app.post('/webhooks/fossapay', async (req, res) => {
  const { event, data } = req.body;

  res.status(200).send('OK');

  switch (event) {
    case 'deposit.completed':
      await handleDepositCompleted(data);
      break;

    case 'withdrawal.completed':
      await handleWithdrawalCompleted(data);
      break;

    case 'transfer.completed':
      await handleTransferCompleted(data);
      break;

    case 'transfer.failed':
      await handleTransferFailed(data);
      break;

    case 'wallet.balance.updated':
      await handleWalletBalanceUpdated(data);
      break;

    default:
      console.log('Unhandled event:', event);
  }
});