Deposits

Available Deposit Events

EVENT	DESCRIPTION
`banking.deposit.pending`	The deposit into an Account with deposit address capabilities has been settled. Associated with Accounts of type `VIRTUAL_EXTERNAL`
`banking.deposit.settled`	The deposit into an Account with deposit address capabilities has been settled. Associated with Accounts of type `VIRTUAL_EXTERNAL`
`banking.prefund.settled`	A deposit into an Account of type `VIRTUAL_WALLET` has been settled into the balance

Sample Deposit Event

{
    "id": "0196910c-ea1b-7e35-bfa1-9dd5cacd76f8",
    "event": "banking.deposit.settled",
    "timestamp": 1746189127535,
    "data": {
        "id": "01961ef1-b671-74c9-97d4-a3aa37e93651",
        "state": "COMPLETED",
        "status_description": "Deposit completed successfully",
        "created_date": "2025-04-10T09:04:39.537Z",
        "updated_date": "2025-04-10T09:04:39.951Z",
        "completion_date": "2025-04-10T09:04:39.503Z",
        "type": "BANK_TRANSFER",
        "internal_reference": "wz-payin-g8kV-1744275879536",
        "client_metadata": {},
        "account_id": "01961ef1-b21c-79ea-a3f3-4764c3b988ba",
        "gross_amount": {
            "value": 1000000000,
            "currency": "NGN"
        },
        "total_fees": {
            "value": 0,
            "currency": "NGN"
        },
        "settled_amount": {
            "value": 1000000000,
            "currency": "NGN"
        },
        "narration": "Sandbox deposit",
        "sender": {
            "type": "SWIFT",
            "bank_name": "Waza Bank",
            "swift_code": "WAZANGUS33",
            "account_number": "1234567890"
        },
        "deposit_references": [
            {
                "type": "GENERIC",
                "value": "0480713436883861"
            }
        ],
        "balance_before": {
            "value": 0,
            "currency": "NGN"
        },
        "balance_after": {
            "value": 1000000000,
            "currency": "NGN"
        }
    }
}

Deposit Event Schema Definition

Field	Data Type	Description
`id`	`string`	Unique identifier for the webhook event (UUID format)
`event`	`string`	Type of event see deposit events
`timestamp`	`number`	Unix timestamp in milliseconds when the event was generated
`data`	`object`	An object containing data about the deposit See section below

Deposit Object Definition

This document describes the structure of deposit payload.

Core Fields

Field	Type	Description
`id`	`string`	Unique identifier for the deposit
`created_at`	`string`	Timestamp when the deposit was created
`updated_at`	`string`	Timestamp when the deposit was last updated
`state`	`string`	Current status of the deposit
`status_description`	`string`	Human-readable description of the deposit status
`completion_date`	`string`	Timestamp when the deposit was completed
`account_id`	`string`	Unique identifier of the account receiving the deposit
`internal_reference`	`string`	System-generated reference for the deposit
`client_metadata`	`string`	Additional metadata provided by the sender
`type`	`string`	Type of deposit see deposit type

Deposit Type

Field	Type	Description
`type`	`enum`	Type of deposit transaction

Possible values:

BANK_TRANSFER - Standard bank transfer deposit
WALLET_PREFUND - Internal wallet funding transaction

Amount Information

Field	Type	Description
`gross_amount`	`object`	Total amount of the deposit before fees
`total_fees`	`object`	Fees deducted from the deposit
`settled_amount`	`object`	Net amount credited to the account

Each amount object contains:

Field	Type	Description
`value`	`number`	Amount in minor units (kobo, cents, pence...)
`currency`	`string`	The Currency code for the value e.g "NGN", "USD"

Sender Information

Field	Type	Description
`narration`	`string`	Additional notes about the deposit
`sender_reference`	`string`	Reference provided by the sender
`sender`	`object`	Information about the sending party

The sender object contains:

Field	Type	Description
`id`	`string`	Unique identifier of the sender
`type`	`string`	Type of sender (e.g., "CounterParty")
`name`	`string`	Name of the sender
`details`	`string`	Additional details about the sender

Identifiers and References

Field	Type	Description
`provider_references`	Array	List of system identifiers for tracking

Each provider reference contains:

Field	Type	Description
`type`	`string`	Type of the reference
`value`	`string`	Value of the reference

Common reference types include:

TRANSACTION_ID - Provider's transaction identifier
BATCH_ID - Batch processing identifier
SESSION_ID - Session identifier

Sub-account Information

Field	Type	Description
`on_behalf_of_account`	`object`	Optional sub-account details

This field is present when a deposit is received on behalf of a sub-account managed by the institution.:

Field	Type	Description
`id`	`string`	Unique Identifier of the sub-account