Statement API

The Statement API allows you to retrieve financial statements and transaction details for your Boya account. This document outlines the structure of the API response and explains key components.

Endpoint

GET /v1/wallet/all-in-one/{currency_ref}

Test the endpoint

Response Structure

The API returns a paginated list of statement entries, each representing a financial transaction.

Top-level Response

Field	Type	Description
docs	array	An array of statement entries
total	number	Total number of entries matching the query
limit	string	Number of entries per page
page	string	Current page number
pages	number	Total number of pages

Statement Entry

Each entry in the docs array represents a financial transaction and has the following structure:

Field	Type	Description
_id	string	Unique identifier for the statement entry
currency	string	Currency code (e.g., "USD")
org_wallet_ref	string	Reference to the organization's wallet
account	string	Account number associated with the transaction
credit	number	Amount credited (if applicable)
debit	number	Amount debited (if applicable)
counter	number	Transaction counter
description	string	Description of the transaction
ref	string	Transaction reference number
created_by	string	Identifier of the user or system that created the entry
transaction_type	string	Type of transaction (e.g., "EXPENSE", "TOPUP", "REFUND", "REVERSAL")
running_balance	number	Account balance after this transaction
business_running_balance	number	Business account balance after this transaction
createdAt	string	Timestamp of when the entry was created
updatedAt	string	Timestamp of when the entry was last updated

Transaction Details

Depending on the transaction_type, additional details are provided in a nested object:

Expense

For transaction_type: "EXPENSE", an expense object is included with details about the expense transaction.

Topup

For transaction_type: "TOPUP", a topup object is included with details about the account top-up.

Refund

For transaction_type: "REFUND", a refund object is included with details about the refund transaction.

Reversal

For transaction_type: "REVERSAL", a refund object is included with details about the reversal transaction (Note: This appears to be using the same structure as a refund in the provided example).

Example Usage

fetch("https://api.boyahq.com/v1/wallet/all-in-one/1")
  .then((response) => response.json())
  .then((data) => {
    console.log(`Total entries: ${data.total}`);
    data.docs.forEach((entry) => {
      console.log(
        `Transaction: ${entry.description}, Amount: ${
          entry.credit || -entry.debit
        } ${entry.currency}`
      );
    });
  });

Pagination

Use the page and limit query parameters to navigate through paginated results:

GET /v1/wallet/all-in-one/1?page=2&limit=25

Error Handling

For information on error codes and handling, please consult our Error Handling Guide.

Additional Notes

All timestamps are in ISO 8601 format.
Amounts are represented as numbers, with debits being positive and credits being negative.
The running_balance and business_running_balance fields provide a snapshot of account balances after each transaction.

For more detailed information on working with financial data, please refer to our comprehensive financial reporting guide.