Account Statements

Overview

The Account Statements API allows you to generate, retrieve, and download financial statements for accounts within your institution. Statements provide a comprehensive view of all transactions during a specified period, including opening and closing balances, transaction details, and summary information.

Key features of the Account Statements API:

Generate statements for specific date ranges
Download statements in various formats (PDF, CSV)
Access detailed transaction data within statements
Retrieve structured statement data in JSON format
View summary information such as total credits, debits, and balance changes

Statements serve as official records of account activity for reconciliation, reporting, tax purposes, and providing financial information to your customers.

The Statement Object

Property	Type	Required	Description
id	string (UUID)	✅	Unique identifier of the statement.
created_at	string (datetime)	✅	The date the statement was created.
state	enum	✅	Current state of the statement (PENDING, PROCESSING, COMPLETE, FAILED).
format	enum	✅	The format of the statement (pdf, csv).
from	string (date)	✅	The start date of the statement period.
to	string (date)	✅	The end date of the statement period.
account_id	string (UUID)	✅	The unique identifier of the account.

The Statement Details Object (JSON format)

When retrieving statement data in JSON format, you'll receive a more detailed object:

Property	Type	Required	Description
id	string (UUID)	✅	Unique identifier of the statement.
created_at	string (datetime)	✅	The date the statement was created.
period	object	✅	Statement period details.
period.from_date	string (date)	✅	The start date of the statement period.
period.to_date	string (date)	✅	The end date of the statement period.
account	object	✅	Account details.
account.id	string (UUID)	✅	The unique identifier of the account.
account.name	string	✅	The name of the account.
account.currency	string	✅	The currency of the account (ISO 4217).
account.client_reference	string	❌	Institution generated client reference of the account.
balances	object	✅	Balance information.
balances.opening_ledger_balance	object	✅	Opening ledger balance.
balances.closing_ledger_balance	object	✅	Closing ledger balance.
balances.opening_available_balance	object	✅	Opening available balance.
balances.closing_available_balance	object	✅	Closing available balance.
summary	object	✅	Transaction summary information.
summary.total_entries	object	✅	Summary of all entries.
summary.total_entries.count	number	✅	Total number of transactions.
summary.total_entries.net_entry_amount	object	✅	Net amount of all transactions.
summary.total_entries.indicator	enum	✅	Overall indicator ('credit' or 'debit').
summary.total_credit_entries	object	✅	Summary of credit entries.
summary.total_credit_entries.count	number	✅	Number of credit transactions.
summary.total_credit_entries.sum	object	✅	Total amount of credit transactions.
summary.total_debit_entries	object	✅	Summary of debit entries.
summary.total_debit_entries.count	number	✅	Number of debit transactions.
summary.total_debit_entries.sum	object	✅	Total amount of debit transactions.
entries	array	✅	List of transaction entries.

Understanding Statement Entry Items

When working with the Account Statements API, it's important to understand that the entries array in the statement JSON doesn't contain a completely new data structure. Instead, each entry item is fundamentally a Transaction object that you're already familiar with from the Transactions API, but with one significant enhancement:

Each entry in the statement is a standard Transaction object with the related_entity field expanded to include detailed information about the originating operation:

The Key Enhancement: Expanded Related Entity

In the regular Transactions API, the related_entity field only contains basic reference information:

// Regular Transaction object from Transactions API
{
  "id": "12345678-1234-1234-1234-123456789012",
  "account_id": "fedcba98-7654-3210-fedc-ba9876543210",
  "state": "COMPLETED",
  "created_date": "2023-05-05T14:30:00Z",
  "completion_date": "2023-05-05T14:35:22Z",
  "amount": {
    "value": 100000,
    "currency": "USD"
  },
  "type": "credit",
  "related_entity": {
    "type": "deposit",
    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  },
  // Other transaction fields...
}

However, in statement entries, the related_entity is expanded to include a data field containing the complete associated object:

// Entry item in Statement
{
  "id": "12345678-1234-1234-1234-123456789012",
  "account_id": "fedcba98-7654-3210-fedc-ba9876543210",
  "state": "COMPLETED",
  "created_date": "2023-05-05T14:30:00Z",
  "completion_date": "2023-05-05T14:35:22Z",
  "amount": {
    "value": 100000,
    "currency": "USD"
  },
  "type": "credit",
  "related_entity": {
    "type": "deposit",
    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "data": {
      // Complete Deposit object
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "state": "COMPLETED",
      "created_date": "2023-05-05T14:30:00Z",
      "type": "BANK_TRANSFER",
      "narration": "Customer payment",
      // All other deposit fields...
    }
  },
  // Other transaction fields...
}

The data field inside related_entity contains a complete object that corresponds to the type of the related entity:

For type: "deposit", the data field contains a complete Deposit object
For type: "transfer", the data field contains a complete Transfer object
For type: "conversion", the data field contains a complete Conversion object

This means that while using the standard Transactions API, you would need to make separate API calls to retrieve detailed information about deposits, transfers, or conversions. Still, with statement entries, this information is already included.

This design allows for efficient and comprehensive processing of financial data in one integrated structure, combining the simplicity of the Transaction model with the rich detail of the specific operation types.

Endpoints

List Statements

Retrieve a paginated list of statements for your institution.

GET /v2/statements

Query Parameters

Parameter	Type	Required	Description
account_id	string (UUID)	❌	Filter statements by account ID.
format	enum	❌	Filter statements by format (pdf, csv).
state	enum	❌	Filter statements by state (PENDING, PROCESSING, COMPLETE, FAILED).
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/statements?account_id=abcdef12-3456-7890-abcd-ef1234567890" \
  -H "x-waza-api-key: your_api_key_here"

Example Response

{
  "data": {
    "items": [
      {
        "id": "abcdef12-3456-7890-abcd-ef1234567890",
        "created_at": "2023-06-01T12:00:00Z",
        "updated_at": "2023-06-01T12:05:22Z",
        "state": "COMPLETE",
        "format": "pdf",
        "from": "2023-05-01",
        "to": "2023-05-31",
        "account_id": "fedcba98-7654-3210-fedc-ba9876543210"
      }
    ],
    "page": 1,
    "limit": 20,
    "totalItems": 1
  }
}

Create Statement

Generate a new statement for a specific account and date range.

POST /v2/statements

Request Body

Parameter	Type	Required	Description
account_id	string (UUID)	✅	The unique identifier of the account.
from	string (date)	✅	The start date of the statement period (YYYY-MM-DD).
to	string (date)	✅	The end date of the statement period (YYYY-MM-DD).
format	enum	✅	The format of the statement (pdf, csv).

Example Request

curl -X POST "https://api.sandbox.waza.co/lync/banking/v2/statements" \
  -H "x-waza-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "fedcba98-7654-3210-fedc-ba9876543210",
    "from": "2023-05-01",
    "to": "2023-05-31",
    "format": "pdf"
  }'

Example Response

{
  "data": {
    "id": "abcdef12-3456-7890-abcd-ef1234567890",
    "created_at": "2023-06-01T12:00:00Z",
    "updated_at": "2023-06-01T12:00:00Z",
    "state": "PENDING",
    "format": "pdf",
    "from": "2023-05-01",
    "to": "2023-05-31",
    "account_id": "fedcba98-7654-3210-fedc-ba9876543210"
  }
}

Get Statement by ID

Retrieve details for a specific statement.

GET /v2/statements/{id}

Path Parameters

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

Example Request

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

Example Response

{
  "data": {
    "id": "abcdef12-3456-7890-abcd-ef1234567890",
    "created_at": "2023-06-01T12:00:00Z",
    "updated_at": "2023-06-01T12:05:22Z",
    "state": "COMPLETE",
    "format": "pdf",
    "from": "2023-05-01",
    "to": "2023-05-31",
    "account_id": "fedcba98-7654-3210-fedc-ba9876543210"
  }
}

Download Statement

Download a statement file in the format it was generated in.

GET /v2/statements/{id}/download

Path Parameters

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

Example Request

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

Response

Binary file stream with the appropriate Content-Type header (application/pdf or text/csv).

Get Statement JSON Data

Retrieve the statement data in JSON format for more detailed processing.

GET /v2/statements/{id}/data

Path Parameters

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

Example Request

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

Example Response

{
  "data": {
    "id": "abcdef12-3456-7890-abcd-ef1234567890",
    "created_at": "2023-06-01T12:00:00Z",
    "period": {
      "from_date": "2023-05-01",
      "to_date": "2023-05-31"
    },
    "account": {
      "id": "fedcba98-7654-3210-fedc-ba9876543210",
      "name": "Main Operating Account",
      "currency": "USD",
      "client_reference": "ops-account-001"
    },
    "balances": {
      "opening_ledger_balance": {
        "value": 500000,
        "currency": "USD"
      },
      "closing_ledger_balance": {
        "value": 750000,
        "currency": "USD"
      },
      "opening_available_balance": {
        "value": 500000,
        "currency": "USD"
      },
      "closing_available_balance": {
        "value": 750000,
        "currency": "USD"
      }
    },
    "summary": {
      "total_entries": {
        "count": 15,
        "net_entry_amount": {
          "value": 250000,
          "currency": "USD"
        },
        "indicator": "credit"
      },
      "total_credit_entries": {
        "count": 10,
        "sum": {
          "value": 500000,
          "currency": "USD"
        }
      },
      "total_debit_entries": {
        "count": 5,
        "sum": {
          "value": 250000,
          "currency": "USD"
        }
      }
    },
    "entries": [
      {
        "id": "12345678-1234-1234-1234-123456789012",
        "account_id": "fedcba98-7654-3210-fedc-ba9876543210",
        "state": "COMPLETED",
        "created_date": "2023-05-05T14:30:00Z",
        "completion_date": "2023-05-05T14:35:22Z",
        "amount": {
          "value": 100000,
          "currency": "USD"
        },
        "type": "credit",
        "balance_before": {
          "value": 500000,
          "currency": "USD"
        },
        "balance_after": {
          "value": 600000,
          "currency": "USD"
        },
        "action": "inbound_funds",
        "related_entity": {
          "type": "deposit",
          "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "data": {
            "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
            "state": "COMPLETED",
            "created_date": "2023-05-05T14:30:00Z",
            "type": "BANK_TRANSFER",
            "narration": "Customer payment",
            "sender": {
              "name": "Acme Inc.",
              "bank_account": {
                "bank_name": "Chase Bank",
                "account_number": "****5678"
              }
            }
          }
        }
      }
      // Additional entries...
    ]
  }
}

Statement States

State	Description
PENDING	Statement generation has been requested but not yet started.
PROCESSING	Statement is currently being generated.
COMPLETE	Statement has been successfully generated and is available for download.
FAILED	Statement generation failed.

Statement Formats

Format	Description	Content-Type
pdf	Portable Document Format suitable for printing and archiving.	application/pdf
csv	Comma-Separated Values format for data analysis and import into spreadsheets.	text/csv