Overview

The Deposits API allows you to retrieve information about incoming funds that have been credited to your accounts. Deposits represent money received into your accounts from external sources, such as bank transfers, domestic payment systems, or wallet prefunding operations.

Key features of the Deposits API:

View detailed information about deposits to your accounts
Track deposit status and settlement information
Access sender details when available
Filter deposits by multiple criteria
Search deposits using reference numbers and keywords

With the Deposits API, you can integrate deposit information into your systems for reconciliation, reporting, and customer notifications.

The Deposit Object

Property	Type	Required	Description
id	string (UUID)	✅	Unique identifier of the deposit.
state	enum	✅	Current state of the deposit (PENDING, COMPLETED, FAILED, CANCELLED).
status_description	string	❌	Human-readable description of the deposit's current state.
created_date	string (datetime)	✅	Date and time when the deposit was created.
updated_date	string (datetime)	✅	Date and time when the deposit was last updated.
completion_date	string (datetime)	✅	Date and time when the deposit was completed (only for COMPLETED deposits).
type	enum	✅	Type of the deposit (BANK_TRANSFER, WALLET_PREFUND).
internal_reference	string	✅	Internal reference for the deposit.
client_metadata	object	✅	Client-provided metadata that can be added to a deposit.
account_id	string (UUID)	✅	ID of the account that received the deposit.
gross_amount	object	✅	Original amount of the deposit before fees.
gross_amount.value	number	✅	Amount in minor units (cents, pence, etc).
gross_amount.currency	string	✅	Currency code (ISO 4217).
total_fees	object	✅	Total fees deducted from the deposit.
total_fees.value	number	✅	Fee amount in minor units (cents, pence, etc).
total_fees.currency	string	✅	Currency code (ISO 4217).
settled_amount	object	✅	Net amount settled to the account after fees.
settled_amount.value	number	✅	Amount in minor units (cents, pence, etc).
settled_amount.currency	string	✅	Currency code (ISO 4217).
narration	string	❌	Description or narration provided with the deposit.
sender_reference	string	❌	Reference provided by the sender.
sender	object	✅	Details about the sender (when available).
sender.name	string	❌	Name of the sender.
sender.country_code	string	❌	Country code of the sender.
sender.bank_account	object	❌	Bank account details of the sender.
provider_references	array	✅	List of references from the payment provider.
provider_references[].type	enum	✅	Type of reference (SESSION_ID, SWIFT_UETR, END_TO_END_ID, etc.).
provider_references[].value	string	✅	Value of the reference.
balance_before	object	✅	Account balance before the deposit.
balance_before.value	number	✅	Amount in minor units (cents, pence, etc).
balance_before.currency	string	✅	Currency code (ISO 4217).
balance_after	object	❌	Account balance after the deposit.
balance_after.value	number	✅	Amount in minor units (cents, pence, etc).
balance_after.currency	string	✅	Currency code (ISO 4217).
on_behalf_of_account	object	❌	Details if the deposit was received on behalf of a sub-account.
on_behalf_of_account.id	string (UUID)	❌	ID of the sub-account.

Example

{
  "data": {
    "id": "abcdef12-3456-7890-abcd-ef1234567890",
    "state": "COMPLETED",
    "status_description": "Deposit completed successfully",
    "created_date": "2023-05-14T10:30:45Z",
    "updated_date": "2023-05-14T10:35:22Z",
    "completion_date": "2023-05-14T10:35:22Z",
    "type": "BANK_TRANSFER",
    "internal_reference": "WZ-DEP-12345",
    "client_reference": "CLIENT-DEP-001",
    "client_metadata": {
      "department": "finance",
      "purpose": "operational"
    },
    "account_id": "fedcba98-7654-3210-fedc-ba9876543210",
    "gross_amount": {
      "value": 100000,
      "currency": "USD"
    },
    "total_fees": {
      "value": 0,
      "currency": "USD"
    },
    "settled_amount": {
      "value": 100000,
      "currency": "USD"
    },
    "narration": "Payment for services",
    "sender_reference": "INV-2023-05-14",
    "sender": {
      "name": "Acme Inc.",
      "country_code": "US",
      "bank_account": {
        "bank_name": "Chase Bank",
        "account_number": "****5678"
      }
    },
    "provider_references": [
      {
        "type": "SESSION_ID",
        "value": "TX123456789"
      }
    ],
    "balance_before": {
      "value": 500000,
      "currency": "USD"
    },
    "balance_after": {
      "value": 600000,
      "currency": "USD"
    }
  }
}

Deposit Sender Bank Account Details

The sender.bank_account object in the Deposit API response contains information about the bank account from which funds were sent. The structure and available fields vary based on the source country and payment method.

General Structure

Field	Type	Required	Description
bank_name	string	❌	Name of the sending bank
account_number	string	❌	Masked account number of the sender
routing_number	string	❌	Routing number of the sending bank (for US banks)
sort_code	string	❌	Sort code of the sending bank (for UK banks)
iban	string	❌	Masked IBAN of the sender (for SEPA transfers)
local_bank_code	string	❌	Local bank code specific to the country
swift_code	string	❌	SWIFT/BIC code of the sending bank

Country-Specific Structures

Nigerian (NGN) Bank Account Details

For deposits from Nigerian banks, the sender.bank_account includes specific Nigerian banking identifiers:

Field	Type	Required	Description
bank_name	string	✅	Name of the Nigerian bank (e.g., "Access Bank", "Guaranty Trust Bank")
bank_code	string	✅	Official Nigerian bank code (3-6 digits)
nip_code	string	❌	Nigerian Inter-bank Payment (NIP) code
account_number	string	✅	Masked account number

European SEPA Bank Account Details

For deposits via SEPA:

Field	Type	Required	Description
bank_name	string	❌	Name of the European bank
iban	string	✅	Masked IBAN (International Bank Account Number)
bic_swift	string	❌	BIC/SWIFT code of the sending bank

UK Bank Account Details

For deposits from UK banks:

Field	Type	Required	Description
bank_name	string	❌	Name of the UK bank
sort_code	string	✅	6-digit UK bank sort code
account_number	string	✅	Masked 8-digit UK account number

Examples

Example: Nigerian (NGN) Bank Account

"sender": {
  "name": "John Okafor",
  "country_code": "NG",
  "bank_account": {
    "bank_name": "Guaranty Trust Bank",
    "bank_code": "058",
    "account_number": "4433435678",
    "account_name": "JOHN OKAFOR"
  }
}

Example: US Bank Account

"sender": {
  "name": "Acme Inc.",
  "country_code": "US",
  "bank_account": {
    "bank_name": "Chase Bank",
    "routing_number": "00000021",
    "account_number": "00005678",
    "account_type": "checking"
  }
}

Example: European SEPA Account

"sender": {
  "name": "Deutsche GmbH",
  "country_code": "DE",
  "bank_account": {
    "bank_name": "Deutsche Bank",
    "iban": "DE8988478549333000"
  }
}

Important Notes

Data Availability: The completeness of sender bank account information depends on what is provided by the sending bank and payment network. Some fields may be unavailable for certain transactions.

Endpoints

List Deposits

Retrieve a paginated list of deposits for your accounts.

v2/deposits

Query Parameters

Parameter	Type	Required	Description
account_id	string (UUID)	❌	Filter deposits by account ID.
state	enum	❌	Filter deposits by state (PENDING, COMPLETED, FAILED, CANCELLED).
completion_date_from	string (datetime)	❌	Filter deposits completed on or after this date.
completion_date_to	string (datetime)	❌	Filter deposits completed on or before this date.
created_date_from	string (datetime)	❌	Filter deposits created on or after this date.
created_date_to	string (datetime)	❌	Filter deposits created on or before this date.
keyword	string	❌	Search keyword in deposit details (min: 4, max: 64 characters).
page	number	❌	Page number for pagination. Default: 1.
limit	number	❌	Number of items per page. Default: 20.

Example Request

curl -X GET "https://api.sandbox.waza.co/lync/banking/v2/deposits?account_id=abcdef12-3456-7890-abcd-ef1234567890&state=COMPLETED" \
  -H "x-waza-api-key: your_api_key_here"

Example Response

{
  "data": {
    "items": [
      {
        "id": "abcdef12-3456-7890-abcd-ef1234567890",
        "state": "COMPLETED",
        "status_description": "Deposit completed successfully",
        "created_date": "2023-05-14T10:30:45Z",
        "updated_date": "2023-05-14T10:35:22Z",
        "completion_date": "2023-05-14T10:35:22Z",
        "type": "BANK_TRANSFER",
        "internal_reference": "WZ-DEP-12345",
        "client_reference": "CLIENT-DEP-001",
        "client_metadata": {
          "department": "finance",
          "purpose": "operational"
        },
        "account_id": "fedcba98-7654-3210-fedc-ba9876543210",
        "gross_amount": {
          "value": 100000,
          "currency": "USD"
        },
        "total_fees": {
          "value": 0,
          "currency": "USD"
        },
        "settled_amount": {
          "value": 100000,
          "currency": "USD"
        },
        "narration": "Payment for services",
        "sender_reference": "INV-2023-05-14",
        "sender": {
          "name": "Acme Inc.",
          "country_code": "US",
          "bank_account": {
            "bank_name": "Chase Bank",
            "account_number": "****5678"
          }
        },
        "provider_references": [
          {
            "type": "SESSION_ID",
            "value": "TX123456789"
          }
        ],
        "balance_before": {
          "value": 500000,
          "currency": "USD"
        },
        "balance_after": {
          "value": 600000,
          "currency": "USD"
        }
      }
    ],
    "page": 1,
    "limit": 20,
    "totalItems": 1
  }
}

Get Deposit by ID

Retrieve details for a specific deposit.

v2/deposits/{id}

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	✅	Unique identifier of the deposit.

Example Request

curl -X GET "https://api.sandbox.waza.co/lync/banking/v2/deposits/abcdef12-3456-7890-abcd-ef1234567890" \
  -H "x-waza-api-key: your_api_key_here"

Example Response

{
  "data": {
    "id": "abcdef12-3456-7890-abcd-ef1234567890",
    "state": "COMPLETED",
    "status_description": "Deposit completed successfully",
    "created_date": "2023-05-14T10:30:45Z",
    "updated_date": "2023-05-14T10:35:22Z",
    "completion_date": "2023-05-14T10:35:22Z",
    "type": "BANK_TRANSFER",
    "internal_reference": "WZ-DEP-12345",
    "client_reference": "CLIENT-DEP-001",
    "client_metadata": {
      "department": "finance",
      "purpose": "operational"
    },
    "account_id": "fedcba98-7654-3210-fedc-ba9876543210",
    "gross_amount": {
      "value": 100000,
      "currency": "USD"
    },
    "total_fees": {
      "value": 0,
      "currency": "USD"
    },
    "settled_amount": {
      "value": 100000,
      "currency": "USD"
    },
    "narration": "Payment for services",
    "sender_reference": "INV-2023-05-14",
    "sender": {
      "name": "Acme Inc.",
      "country_code": "US",
      "bank_account": {
        "bank_name": "Chase Bank",
        "account_number": "****5678"
      }
    },
    "provider_references": [
      {
        "type": "SESSION_ID",
        "value": "TX123456789"
      }
    ],
    "balance_before": {
      "value": 500000,
      "currency": "USD"
    },
    "balance_after": {
      "value": 600000,
      "currency": "USD"
    }
  }
}

Deposit Types

The API supports the following deposit types:

Type	Description
BANK_TRANSFER	Standard bank transfer from an external account
WALLET_PREFUND	Balance top-up for Accounts of type VIRTUAL_WALLET typically handled at a back office level

Deposit States

Deposits can be in one of the following states:

State	Description
PENDING	The deposit has been initiated but not yet settled
COMPLETED	The deposit has been successfully settled to the account
FAILED	The deposit failed to complete
CANCELLED	The deposit was cancelled

Provider Reference Types

The provider_references array may contain references of the following types:

Type	Description
SESSION_ID	Provider-specific session identifier
SWIFT_UETR	SWIFT Unique End-to-End Transaction Reference
END_TO_END_ID	End-to-end identifier for the transaction
IMAD	Input Message Accountability Data
OMAD	Output Message Accountability Data
GENERIC	Generic reference type

Simulating Deposits in Sandbox

In the sandbox environment, you can simulate deposits to test your integration:

POST /v2/sandbox/deposit

Request Body

Parameter	Type	Required	Description
account_id	string (UUID)	✅	Account (or SubAccount) ID or to simulate deposit to.
amount	number	✅	Amount to simulate deposit in minor units.
fee	number	❌	Fee to deduct from deposit in minor units.
description	string	❌	Description for the simulated deposit.
identifiers	array	❌	List of scheme identifiers to include with the deposit.

Example Request

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/sandbox/deposit" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "fedcba98-7654-3210-fedc-ba9876543210",
    "amount": 100000,
    "description": "Test deposit"
  }'