Webhook Event Types

VTU API sends webhooks for the following transaction events:

Event	Description
transaction.success	Transaction completed successfully
transaction.failed	Transaction failed
transaction.refunded	Transaction was refunded
transaction.pending	Transaction is pending processing
transaction.status_update	Transaction status changed

Payload Structure

All webhook payloads follow this structure:

{
  "event": "<event_type>",
  "event_type": "<event_type>",
  "timestamp": "<ISO 8601 datetime>",
  "webhook_id": 2,
  "user_id": 178,
  "data": {
    "id": 41251,
    "reference": "<transaction_reference>",
    "amount": "206.00",
    "currency": "NGN",
    "status": "<status>",
    "type": "<transaction_model>",
    "balance_before": "14184",
    "balance_after": "14390",
    "created_at": "<ISO 8601>",
    "updated_at": "<ISO 8601>"
  },
  "metadata": {},
  "version": "1.0"
}

Payload Fields

Field	Type	Description
event	string	Event type identifier
event_type	string	Same as event (for compatibility)
timestamp	string	ISO 8601 timestamp of event dispatch
webhook_id	integer	Your webhook configuration ID
user_id	integer	Your user ID
data	object	Transaction data
data.id	integer	Transaction ID
data.reference	string	Unique transaction reference
data.amount	string	Transaction amount
data.currency	string	Currency code (e.g., "NGN")
data.status	string	Current transaction status
data.type	string	Transaction model type
data.balance_before	string	Wallet balance before transaction
data.balance_after	string	Wallet balance after transaction
metadata	object	Additional event-specific metadata
version	string	Payload version

---

Example: transaction.success

Sent when a transaction completes successfully (e.g., data purchase, airtime top-up).

{
  "event": "transaction.success",
  "event_type": "transaction.success",
  "timestamp": "2025-10-17T18:30:00+01:00",
  "webhook_id": 2,
  "user_id": 178,
  "data": {
    "id": 41251,
    "reference": "DT20251016185459609091",
    "amount": "206.00",
    "currency": "NGN",
    "status": "success",
    "type": "App\\Models\\DataTransaction",
    "balance_before": "14184",
    "balance_after": "14390",
    "created_at": "2025-10-16T17:54:59.000000Z",
    "updated_at": "2025-10-17T18:30:00.000000Z"
  },
  "metadata": {
    "previous_status": "pending",
    "updated_by": "admin@system.com",
    "admin_action": true
  },
  "version": "1.0"
}

---

Example: transaction.refunded

Sent when a transaction is refunded and the amount is credited back to the user's wallet.

{
  "event": "transaction.refunded",
  "event_type": "transaction.refunded",
  "timestamp": "2025-10-17T18:35:00+01:00",
  "webhook_id": 2,
  "user_id": 178,
  "data": {
    "id": 41252,
    "reference": "TX102025654321",
    "amount": "206.00",
    "currency": "NGN",
    "status": "refunded",
    "type": "App\\Models\\DataTransaction",
    "balance_before": "14184",
    "balance_after": "14390",
    "created_at": "2025-10-17T18:35:00.000000Z",
    "updated_at": "2025-10-17T18:35:00.000000Z"
  },
  "metadata": {
    "refund_amount": 206.00,
    "refund_reason": "Admin initiated refund",
    "original_transaction_id": 41251,
    "original_reference": "DT20251016185459609091",
    "processed_by": "admin@system.com"
  },
  "version": "1.0"
}

Refund Metadata Fields

Field	Type	Description
refund_amount	number	The refunded amount
refund_reason	string	Reason for the refund
original_transaction_id	integer	ID of the original transaction
original_reference	string	Reference of the original transaction
processed_by	string	Who initiated the refund

---

Example: transaction.failed

Sent when a transaction fails.

{
  "event": "transaction.failed",
  "event_type": "transaction.failed",
  "timestamp": "2025-10-17T18:40:00+01:00",
  "webhook_id": 2,
  "user_id": 178,
  "data": {
    "id": 41253,
    "reference": "DT20251017184000123456",
    "amount": "500.00",
    "currency": "NGN",
    "status": "failed",
    "type": "App\\Models\\DataTransaction",
    "balance_before": "14390",
    "balance_after": "14390",
    "created_at": "2025-10-17T18:40:00.000000Z",
    "updated_at": "2025-10-17T18:40:00.000000Z"
  },
  "metadata": {
    "failure_reason": "Provider service unavailable"
  },
  "version": "1.0"
}