Deposit Events
deposit.completed
Fired when a deposit is completed successfully.Crypto Deposit
{
"event": "deposit.completed",
"eventId": "evt_abc123",
"timestamp": "2024-01-15T10:30:45Z",
"data": {
"transactionId": "txn_001",
"customerId": "cus_123",
"sender": {
"address": "0x123...",
"chain": "Ethereum"
},
"recipient": {
"address": "0x456...",
"chain": "Ethereum"
},
"amount": 1000000,
"currency": "USDT",
"reference": "dep-20240115-001",
"status": "completed",
"transactionType": "deposit",
"blockchain": "Ethereum",
"transactionHash": "0x789...",
"explorer_link": "https://etherscan.io/tx/0x789...",
"timestamp": "2024-01-15T10:30:40Z"
}
}
Fiat Deposit
{
"event": "deposit.completed",
"eventId": "evt_def456",
"timestamp": "2024-01-15T11:00:00Z",
"data": {
"transactionId": "txn_002",
"customerId": "cus_456",
"sender": {
"accountName": "John Doe",
"accountNumber": "0987654321",
"bankName": "GTBank"
},
"recipient": {
"accountName": "Jane Smith",
"accountNumber": "0123456789",
"bankName": "GTBank"
},
"amount": 50000,
"currency": "NGN",
"fee": 500,
"reference": "dep-20240115-002",
"status": "completed",
"transactionType": "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",
"eventId": "evt_xyz789",
"timestamp": "2024-01-15T11:45:23Z",
"data": {
"transactionId": "txn_003",
"customerId": "cus_789",
"recipient": {
"accountName": "Jane Smith",
"accountNumber": "0123456789",
"bankName": "GTBank"
},
"amount": 25000,
"currency": "NGN",
"reference": "wth-20240115-001",
"status": "completed",
"transactionType": "withdrawal",
"timestamp": "2024-01-15T11:45:20Z"
}
}
withdrawal.failed
Fired when a withdrawal fails.{
"event": "withdrawal.failed",
"eventId": "evt_xyz789",
"timestamp": "2024-01-15T11:45:23Z",
"data": {
"transactionId": "txn_003",
"customerId": "cus_789",
"recipient": {
"accountName": "Jane Smith",
"accountNumber": "0123456789",
"bankName": "GTBank"
},
"amount": 25000,
"currency": "NGN",
"reference": "wth-20240115-001",
"status": "failed",
"transactionType": "withdrawal",
"timestamp": "2024-01-15T11:45:20Z"
}
}
Transfer Events
transfer.completed
Fired when a transfer is completed successfully.{
"event": "transfer.completed",
"eventId": "evt_transfer1",
"timestamp": "2024-01-15T12:30:00Z",
"data": {
"transactionId": "txn_004",
"customerId": "cus_123",
"sender": {
"address": "0x123...",
"chain": "Ethereum"
},
"recipient": {
"address": "0x456...",
"chain": "Ethereum"
},
"amount": 500000,
"currency": "USDT",
"reference": "trf-20240115-001",
"status": "completed",
"transactionType": "transfer",
"blockchain": "Ethereum",
"transactionHash": "0xabc...",
"timestamp": "2024-01-15T12:30:00Z"
}
}
transfer.failed
Fired when a transfer fails.{
"event": "transfer.failed",
"eventId": "evt_transfer2",
"timestamp": "2024-01-15T13:15:00Z",
"data": {
"transactionId": "txn_005",
"customerId": "cus_456",
"sender": {
"address": "0x789...",
"chain": "Ethereum"
},
"recipient": {
"address": "0xabc...",
"chain": "Ethereum"
},
"amount": 300000,
"currency": "USDT",
"reference": "trf-20240115-002",
"status": "failed",
"transactionType": "transfer",
"blockchain": "Ethereum",
"transactionHash": "0xdef...",
"timestamp": "2024-01-15T13:15:00Z"
}
}
Wallet Events
wallet.balance.updated
Fired when a wallet balance is updated.{
"event": "wallet.balance.updated",
"eventId": "evt_balance1",
"timestamp": "2024-01-15T14:00:00Z",
"data": {
"fromAccount": {
"accountNumber": "0123456789",
"accountName": "Main Wallet",
"bankName": "GTBank"
},
"toAccount": {
"accountNumber": "0987654321",
"accountName": "Savings Wallet",
"bankName": "GTBank",
},
"amount": 25000,
"currency": "NGN",
"reference": "bal-20240115-001",
"type": "withdrawal / deposit",
"customerId": "cus_123",
"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);
}
});