Webhook Events

Every webhook uses the eventId, eventType, data, and timestamp envelope described in the Webhooks Overview.

Checkout Events

Checkout events are emitted when a Checkout Wallet reaches a terminal state. Use data.reference to reconcile the event to your order and eventId to deduplicate deliveries.

checkout.completed

Fired after the exact amountPayable is confirmed and merchant settlement is recorded. This is the only checkout event on which you should fulfill an order.

{
  "eventId": "evt_mtwc9i1y_0409d781714d8fa2",
  "eventType": "checkout.completed",
  "data": {
    "checkoutId": "35f5f6fb-0c8d-4e96-ba4a-c04750724ff6",
    "transactionId": "3469cd26-a213-431e-96c9-72dc2dea51ae",
    "reference": "ORDER-10025",
    "status": "completed",
    "amount": "5000.00",
    "fee": "80.00",
    "amountPayable": "5080.00",
    "settlementAmount": "5000.00",
    "feeBearer": "customer",
    "currency": "NGN",
    "accountType": "temporary",
    "sender": {
      "accountName": "JOHN DOE",
      "accountNumber": "0123456789",
      "bankCode": "100004",
      "bankName": "OPAY"
    },
    "providerReference": "100004260911021740170939156478",
    "metadata": { "orderId": "10025" },
    "expiresAt": "2026-09-11T10:30:00.000Z",
    "completedAt": "2026-09-11T10:08:14.148Z",
    "failedAt": null,
    "reversedAt": null
  },
  "timestamp": "2026-09-11T10:08:14.186Z"
}

sender.bankCode is exposed when the provider supplies a sender bank code. sender.bankName can be null when the upstream provider does not supply the bank name.

checkout.failed

Fired when checkout processing fails, including an incoming transfer that does not equal amountPayable. Do not fulfill the order.

{
  "eventId": "evt_checkout_failed_001",
  "eventType": "checkout.failed",
  "data": {
    "checkoutId": "35f5f6fb-0c8d-4e96-ba4a-c04750724ff6",
    "transactionId": "d7a8bf6c-4a15-489f-9671-0b1c0574661e",
    "reference": "ORDER-10025",
    "status": "failed",
    "amount": "5000.00",
    "fee": "80.00",
    "amountPayable": "5080.00",
    "settlementAmount": "5000.00",
    "feeBearer": "customer",
    "currency": "NGN",
    "accountType": "temporary",
    "sender": {
      "accountName": "JOHN DOE",
      "accountNumber": "0123456789",
      "bankCode": "100004",
      "bankName": null
    },
    "providerReference": "100004260911024224170939264304",
    "metadata": { "orderId": "10025" },
    "expiresAt": "2026-09-11T10:30:00.000Z",
    "completedAt": null,
    "failedAt": "2026-09-11T10:12:29.048Z",
    "reversedAt": null
  },
  "timestamp": "2026-09-11T10:12:29.100Z"
}

checkout.expired

Fired when a pending checkout reaches its expiry or is manually expired.

{
  "eventId": "evt_checkout_expired_001",
  "eventType": "checkout.expired",
  "data": {
    "checkoutId": "35f5f6fb-0c8d-4e96-ba4a-c04750724ff6",
    "transactionId": null,
    "reference": "ORDER-10025",
    "status": "expired",
    "amount": "5000.00",
    "fee": "80.00",
    "amountPayable": "5080.00",
    "settlementAmount": "5000.00",
    "feeBearer": "customer",
    "currency": "NGN",
    "accountType": "temporary",
    "metadata": { "orderId": "10025" },
    "expiresAt": "2026-09-11T10:30:00.000Z"
  },
  "timestamp": "2026-09-11T10:30:00.100Z"
}

checkout.reversed

Fired after an incoming checkout payment is returned to the sender. This can follow a failed temporary-account payment, such as an amount mismatch.

{
  "eventId": "evt_checkout_reversed_001",
  "eventType": "checkout.reversed",
  "data": {
    "checkoutId": "35f5f6fb-0c8d-4e96-ba4a-c04750724ff6",
    "transactionId": "1e72866f-a78b-4d65-a87c-7a37a521322d",
    "reference": "ORDER-10025",
    "status": "reversed",
    "amount": "5000.00",
    "fee": "80.00",
    "amountPayable": "5080.00",
    "settlementAmount": "5000.00",
    "feeBearer": "customer",
    "currency": "NGN",
    "accountType": "temporary",
    "sender": {
      "accountName": "JOHN DOE",
      "accountNumber": "0123456789",
      "bankCode": "100004",
      "bankName": "OPAY"
    },
    "providerReference": "CHK_1789094550_R_d610910474324f4fb690d1e98f73f453",
    "metadata": { "orderId": "10025" },
    "expiresAt": "2026-09-11T10:30:00.000Z",
    "completedAt": null,
    "failedAt": "2026-09-11T10:12:29.048Z",
    "reversedAt": "2026-09-11T10:12:30.605Z"
  },
  "timestamp": "2026-09-11T10:12:30.700Z"
}

Payout Events

Master-wallet payout events are emitted when a payout reaches a terminal state. Use data.reference to reconcile with your request and data.payoutId when retrieving the payout through the API.

payout.completed

Fired when the payout completes successfully. A same-business transfer may produce this event immediately during the create request.

{
  "eventId": "evt_payout_completed_001",
  "eventType": "payout.completed",
  "data": {
    "payoutId": "a9af907d-965f-4ad8-9472-f437fc11df21",
    "transactionId": "5a0bb85c-268b-44fa-a57d-70b2944688bc",
    "reference": "PAYOUT-10025",
    "status": "completed",
    "route": "external_bank",
    "amount": "5000.00",
    "fee": "80.00",
    "totalDebited": "5080.00",
    "currency": "NGN",
    "recipient": {
      "bankCode": "058",
      "bankName": "Guaranty Trust Bank",
      "accountName": "JOHN DOE",
      "accountNumber": "0123456789"
    },
    "providerReference": "PYT_K8Q4D2M7N5R3T9A_1789098000000",
    "metadata": { "invoiceId": "INV-10025" },
    "completedAt": "2026-09-11T12:05:10.000Z",
    "failedAt": null,
    "reversedAt": null
  },
  "timestamp": "2026-09-11T12:05:10.100Z"
}

payout.failed

Fired when a payout fails and does not have a confirmed full reversal. Do not automatically create a replacement payout. Retrieve the payout and contact support if funds remain reserved.

{
  "eventId": "evt_payout_failed_001",
  "eventType": "payout.failed",
  "data": {
    "payoutId": "a9af907d-965f-4ad8-9472-f437fc11df21",
    "transactionId": "5a0bb85c-268b-44fa-a57d-70b2944688bc",
    "reference": "PAYOUT-10025",
    "status": "failed",
    "route": "external_bank",
    "amount": "5000.00",
    "fee": "80.00",
    "totalDebited": "5080.00",
    "currency": "NGN",
    "recipient": {
      "bankCode": "058",
      "bankName": "Guaranty Trust Bank",
      "accountName": "JOHN DOE",
      "accountNumber": "0123456789"
    },
    "providerReference": "PYT_K8Q4D2M7N5R3T9A_1789098000000",
    "metadata": { "invoiceId": "INV-10025" },
    "completedAt": null,
    "failedAt": "2026-09-11T12:05:10.000Z",
    "reversedAt": null
  },
  "timestamp": "2026-09-11T12:05:10.100Z"
}

payout.reversed

Fired when the payout does not complete and FossaPay confirms that the reserved payout amount and fee have been returned to the merchant master wallet.

{
  "eventId": "evt_payout_reversed_001",
  "eventType": "payout.reversed",
  "data": {
    "payoutId": "a9af907d-965f-4ad8-9472-f437fc11df21",
    "transactionId": "5a0bb85c-268b-44fa-a57d-70b2944688bc",
    "reference": "PAYOUT-10025",
    "status": "reversed",
    "route": "external_bank",
    "amount": "5000.00",
    "fee": "80.00",
    "totalDebited": "5080.00",
    "currency": "NGN",
    "recipient": {
      "bankCode": "058",
      "bankName": "Guaranty Trust Bank",
      "accountName": "JOHN DOE",
      "accountNumber": "0123456789"
    },
    "providerReference": "PYT_K8Q4D2M7N5R3T9A_1789098000000",
    "metadata": { "invoiceId": "INV-10025" },
    "completedAt": null,
    "failedAt": "2026-09-11T12:05:10.000Z",
    "reversedAt": "2026-09-11T12:05:12.000Z"
  },
  "timestamp": "2026-09-11T12:05:12.100Z"
}

The route value is one of same_business, fossapay_cross_business, or external_bank. Same-business payouts have a zero fee.

Bulk Payout Events

Bulk payout events are terminal and refer to the FossaPay batch with data.batchId. Verify the webhook signature and deduplicate deliveries using the envelope eventId.

payout.batch.completed

Fired when every item in an immediate batch completes successfully.

{
  "eventId": "evt_bulk_completed_001",
  "eventType": "payout.batch.completed",
  "data": {
    "batchId": "2ebee4e9-e4d7-4cbe-b6ee-eaf75369b851",
    "batchReference": "PAYROLL-2026-09",
    "status": "completed",
    "accountNumber": "9710000000",
    "totalRecipients": 2,
    "totalAmount": "12500.00",
    "totalFee": "60.00",
    "totalDebit": "12560.00",
    "failureReason": null,
    "completedAt": "2026-09-24T09:02:15.000Z",
    "failedAt": null
  },
  "timestamp": "2026-09-24T09:02:15.100Z"
}

payout.batch.failed

Fired when the batch reaches a failed terminal state. Do not automatically submit a replacement batch; retrieve the latest batch status first.

{
  "eventId": "evt_bulk_failed_001",
  "eventType": "payout.batch.failed",
  "data": {
    "batchId": "2ebee4e9-e4d7-4cbe-b6ee-eaf75369b851",
    "batchReference": "PAYROLL-2026-09",
    "status": "failed",
    "accountNumber": "9710000000",
    "totalRecipients": 2,
    "totalAmount": "12500.00",
    "totalFee": "60.00",
    "totalDebit": "12560.00",
    "failureReason": "Provider reported batch failure",
    "completedAt": null,
    "failedAt": "2026-09-24T09:02:15.000Z"
  },
  "timestamp": "2026-09-24T09:02:15.100Z"
}

Deposit Events

deposit.completed

Fired when a deposit is completed successfully.

Crypto Deposit

{
  "eventType": "deposit.completed",
  "eventId": "evt_abc123",
  "timestamp": "2024-01-15T10:30:45Z",
  "data": {
    "transactionId": "44444444-4444-4444-8444-444444444401",
    "customerId": "11111111-1111-4111-8111-111111111111",
    "sender": {
      "address": "So11111111111111111111111111111111111111112",
      "chain": "Solana"
    },
    "recipient": {
      "address": "7EcJ1eB6J3ggRrGkQWsT4ZP8dkqPZ4JmW4YRwR7Qp5cY",
      "chain": "Solana"
    },
    "amount": 1000000,
    "currency": "USDT",
    "reference": "dep-20240115-001",
    "status": "completed",
    "transactionType": "deposit",
    "blockchain": "Solana",
    "transactionHash": "SOLANA_TRANSACTION_SIGNATURE",
    "explorer_link": "https://solscan.io/tx/SOLANA_TRANSACTION_SIGNATURE",
    "timestamp": "2024-01-15T10:30:40Z"
  }
}

NGN Deposit

{
  "eventType": "deposit.completed",
  "eventId": "evt_def456",
  "timestamp": "2024-01-15T11:00:00Z",
  "data": {
    "transactionId": "44444444-4444-4444-8444-444444444402",
    "customerId": "11111111-1111-4111-8111-111111111111",
    "sender": {
      "accountName": "John Doe",
      "accountNumber": "0987654321",
      "bankName": "GTBank"
    },
    "recipient": {
      "accountName": "John Doe",
      "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.

{
  "eventType": "withdrawal.completed",
  "eventId": "evt_xyz789",
  "timestamp": "2024-01-15T11:45:23Z",
  "data": {
    "transactionId": "44444444-4444-4444-8444-444444444403",
    "customerId": "11111111-1111-4111-8111-111111111111",
    "recipient": {
      "accountName": "John Doe",
      "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.

{
  "eventType": "withdrawal.failed",
  "eventId": "evt_xyz789",
  "timestamp": "2024-01-15T11:45:23Z",
  "data": {
    "transactionId": "44444444-4444-4444-8444-444444444403",
    "customerId": "11111111-1111-4111-8111-111111111111",
    "recipient": {
      "accountName": "John Doe",
      "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.

{
  "eventType": "transfer.completed",
  "eventId": "evt_transfer1",
  "timestamp": "2024-01-15T12:30:00Z",
  "data": {
    "transactionId": "44444444-4444-4444-8444-444444444404",
    "customerId": "11111111-1111-4111-8111-111111111111",
    "sender": {
      "address": "So11111111111111111111111111111111111111112",
      "chain": "Solana"
    },
    "recipient": {
      "address": "7EcJ1eB6J3ggRrGkQWsT4ZP8dkqPZ4JmW4YRwR7Qp5cY",
      "chain": "Solana"
    },
    "amount": 500000,
    "currency": "USDT",
    "reference": "trf-20240115-001",
    "status": "completed",
    "transactionType": "transfer",
    "blockchain": "Solana",
    "transactionHash": "SOLANA_TRANSACTION_SIGNATURE",
    "timestamp": "2024-01-15T12:30:00Z"
  }
}

transfer.failed

Fired when a transfer fails.

{
  "eventType": "transfer.failed",
  "eventId": "evt_transfer2",
  "timestamp": "2024-01-15T13:15:00Z",
  "data": {
    "transactionId": "44444444-4444-4444-8444-444444444405",
    "customerId": "11111111-1111-4111-8111-111111111111",
    "sender": {
      "address": "So11111111111111111111111111111111111111112",
      "chain": "Solana"
    },
    "recipient": {
      "address": "7EcJ1eB6J3ggRrGkQWsT4ZP8dkqPZ4JmW4YRwR7Qp5cY",
      "chain": "Solana"
    },
    "amount": 300000,
    "currency": "USDT",
    "reference": "trf-20240115-002",
    "status": "failed",
    "transactionType": "transfer",
    "blockchain": "Solana",
    "transactionHash": "SOLANA_TRANSACTION_SIGNATURE",
    "timestamp": "2024-01-15T13:15:00Z"
  }
}

Wallet Events

wallet.balance.updated

Fired when a wallet balance is updated.

{
  "eventType": "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": "11111111-1111-4111-8111-111111111111",
    "narration": "Transfer between accounts",
    "timestamp": "2024-01-15T14:00:00Z"
  }
}

Example Handler

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

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

  // Deduplicate eventId before running any business action.
  switch (eventType) {
    case 'checkout.completed':
      await handleCheckoutCompleted(data);
      break;

    case 'checkout.failed':
    case 'checkout.expired':
    case 'checkout.reversed':
      await handleCheckoutTerminalState(eventType, data);
      break;

    case 'payout.completed':
      await handlePayoutCompleted(data);
      break;

    case 'payout.failed':
    case 'payout.reversed':
      await handlePayoutTerminalState(eventType, data);
      break;

    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:', eventType, eventId);
  }
});

Customers

Virtual Wallets

Checkout Wallet

Identity Verification

Master Wallet Payouts

NGN Transfers

Bulk Payouts

Crypto Wallets

Crypto Transfers

Webhooks

Checkout Events

checkout.completed

checkout.failed

checkout.expired

checkout.reversed

Payout Events

payout.completed

payout.failed

payout.reversed

Bulk Payout Events

payout.batch.completed

payout.batch.failed

Deposit Events

deposit.completed

Crypto Deposit

NGN Deposit

Withdrawal Events

withdrawal.completed

withdrawal.failed

Transfer Events

transfer.completed

transfer.failed

Wallet Events

wallet.balance.updated

Example Handler

​Checkout Events

​checkout.completed

​checkout.failed

​checkout.expired

​checkout.reversed

​Payout Events

​payout.completed

​payout.failed

​payout.reversed

​Bulk Payout Events

​payout.batch.completed

​payout.batch.failed

​Deposit Events

​deposit.completed

​Crypto Deposit

​NGN Deposit

​Withdrawal Events

​withdrawal.completed

​withdrawal.failed

​Transfer Events

​transfer.completed

​transfer.failed

​Wallet Events

​wallet.balance.updated

​Example Handler

Checkout Events

checkout.completed

checkout.failed

checkout.expired

checkout.reversed

Payout Events

payout.completed

payout.failed

payout.reversed

Bulk Payout Events

payout.batch.completed

payout.batch.failed

Deposit Events

deposit.completed

Crypto Deposit

NGN Deposit

Withdrawal Events

withdrawal.completed

withdrawal.failed

Transfer Events

transfer.completed

transfer.failed

Wallet Events

wallet.balance.updated

Example Handler