Get Account Statement

Retrieves the transaction history for a specific merchant collection account over a given date range. The statement includes both credit and debit transactions with detailed metadata.

Endpoint

GET /account/{account_number}/statement?startDate={startDate}&endDate={endDate}

Request

Headers

Content-Type* — Must be application/json
Authorization* — Bearer token (Bearer YOUR_API_TOKEN)
x-request-id* — Unique UUID per request for tracing

Request URL Parameters

startDate* (string) — Start of the date range (format: YYYY-MM-DD)
endDate* (string) — End of the date range (format: YYYY-MM-DD). Must be on or after startDate

Date Range Rules

Date Format — Use YYYY-MM-DD format (e.g., 2024-12-12)
Date Range — endDate must be on or after startDate
Inclusive Range — Both start and end dates are included in the results

Responses

200 SUCCESS

Response Format

{
  "success": true,
  "statusCode": "SUCCESS",
  "timestamp": "2025-09-11T14:07:00+03:00",
  "result": {
    "accountNo": "XXXXXXXXX",
    "statement": [
      {
        "senderAccountNo": null,
        "senderAccountName": null,
        "senderBankIdentifier": null,
        "valueDate": "2025-08-20T00:00:00+03:00",
        "transactionDate": "2025-08-20T00:00:00+03:00",
        "transactionId": null,
        "reference": "R90ngkb252320003",
        "paymentReference": null,
        "creditOrDebit": "CREDIT",
        "currency": "TZS",
        "amountCredit": 11000,
        "amountDebit": 0,
        "availableBalance": 11000,
        "currentBalance": 11000,
        "narration": "MOBILE TRANSFER 2508201BRYYJ00001: TRN IFO TEMBOPLUS COMPANY LIMITED BO TEMBOPLUS COMPANY LIMITED FOR Book Transfer LCY,Test",
        "description": "MOBILE TRANSFER 2508201BRYYJ00001: TRN IFO TEMBOPLUS COMPANY LIMITED BO TEMBOPLUS COMPANY LIMITED FOR Book Transfer LCY,Test"
      },
      {
        "senderAccountNo": null,
        "senderAccountName": null,
        "senderBankIdentifier": null,
        "valueDate": "2025-08-20T00:00:00+03:00",
        "transactionDate": "2025-08-20T00:00:00+03:00",
        "transactionId": null,
        "reference": "R79ahkk252320002",
        "paymentReference": null,
        "creditOrDebit": "DEBIT",
        "currency": "TZS",
        "amountCredit": 0,
        "amountDebit": 1000,
        "availableBalance": 10000,
        "currentBalance": 10000,
        "narration": "MOBILE TRANSFER TF-1755689719241- B/O TEMBOPLUS COMPANY LIMITED TEMBOPLUS COMPANY LIMITED - OTHER",
        "description": "MOBILE TRANSFER TF-1755689719241- B/O TEMBOPLUS COMPANY LIMITED TEMBOPLUS COMPANY LIMITED - OTHER"
      },
      {
        "senderAccountNo": null,
        "senderAccountName": null,
        "senderBankIdentifier": null,
        "valueDate": "2025-09-10T00:00:00+03:00",
        "transactionDate": "2025-09-10T00:00:00+03:00",
        "transactionId": null,
        "reference": "R79zsuc252530003",
        "paymentReference": null,
        "creditOrDebit": "CREDIT",
        "currency": "TZS",
        "amountCredit": 20000,
        "amountDebit": 0,
        "availableBalance": 30000,
        "currentBalance": 30000,
        "narration": "MOBILE TRANSFER REF:ETZ2532500000020 B/O TEMBOPLUS CO LTD XTRANSFER - DEP1757492490611 null",
        "description": "MOBILE TRANSFER REF:ETZ2532500000020 B/O TEMBOPLUS CO LTD XTRANSFER - DEP1757492490611 null"
      },
      {
        "senderAccountNo": null,
        "senderAccountName": null,
        "senderBankIdentifier": null,
        "valueDate": "2025-09-10T00:00:00+03:00",
        "transactionDate": "2025-09-10T00:00:00+03:00",
        "transactionId": null,
        "reference": "R79CATZTZSL00001",
        "paymentReference": null,
        "creditOrDebit": "DEBIT",
        "currency": "TZS",
        "amountCredit": 0,
        "amountDebit": 15000,
        "availableBalance": 15000,
        "currentBalance": 15000,
        "narration": "CURRENT ACCOUNT MAINTENANCE FEE CURRENT ACCOUNT MAINTENANCE FEE",
        "description": "CURRENT ACCOUNT MAINTENANCE FEE CURRENT ACCOUNT MAINTENANCE FEE"
      }
    ]
  }
}

Response Fields

accountNo (string) — The account number queried
statement (array) — List of transactions within the given period

Statement Transaction Fields

Each item in the statement array contains:

transactionId (string) — Internal transaction UUID
reference (string) — Transaction reference
creditOrDebit (string) — Indicates if the transaction is a CREDIT or DEBIT
transactionDate (string) — Date and time when the transaction occurred
valueDate (string) — Effective date of the transaction
narration (string) — Description or metadata attached to the transaction
currency (string) — Currency code (e.g., TZS)
amountCredit (number) — Amount credited to the account
amountDebit (number) — Amount debited from the account
availableBalance (number) — Available balance after the transaction was cleared
currentBalance (number) — Balance including uncleared (pending) transactions
senderAccountNo (string | null) — Sender's account number (may be null if unavailable)
senderAccountName (string | null) — Sender's account name (may be null if unavailable)
senderBankIdentifier (string | null) — Identifier for sender’s bank (may be null if unavailable)

400 BAD REQUEST

This error occurs when the request contains missing or invalid parameters. The API validates all required fields and data formats before processing your request.

Common causes:

The accountNo field is empty or missing
Missing required date fields (startDate or endDate)
Invalid date format (must be YYYY-MM-DD)
endDate is before startDate
Invalid JSON syntax in the request body
Missing Content-Type: application/json header

Error format:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Validation Error",
  "details": {
    "endDate": "\"endDate\" is required"
  }
}

Or for specific validation issues:

{
  "statusCode": 400,
  "message": "Invalid date format",
  "error": "Validation Error",
  "details": {
    "startDate": "Date must be in YYYY-MM-DD format"
  }
}

Resolution:

Verify all required fields (accountNo, startDate, endDate) are included
Ensure dates are in YYYY-MM-DD format
Confirm endDate is on or after startDate
Validate JSON syntax before sending the request

401 UNAUTHORIZED

This error indicates authentication failure. The API could not verify your identity using the provided credentials.

Common Causes:

Missing Authorization header in the request
Invalid bearer token format (should be Bearer YOUR_TOKEN)
Expired or revoked API token
Incorrect API token value

Error Format

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Invalid or missing authentication token"
}

Resolution

Ensure your request includes the correct authorization header: Authorization: Bearer YOUR_API_TOKEN

404 NOT FOUND

This error indicates that the specified account number does not exist or is not accessible with your current credentials.

Why this happens:

Account number doesn't exist in your allocated pool
Typo in the account number
Account was never successfully allocated

Error format

HTTP 404 status with no response body.

Resolution:

Verify the account number is correct and properly formatted
Confirm the account was successfully allocated using the allocate endpoint

500 INTERNAL SERVER ERROR

This error indicates a temporary server-side issue that prevented the request from being processed. These are typically transient problems that resolve automatically.

Common causes:

Temporary banking system connectivity issues
Server maintenance or updates in progress
Third-party service temporary unavailability

Error format

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Something went wrong"
}

Resolution:

Wait 1-2 minutes and retry the request
Contact support with your x-request-id if the issue persists beyond 10 minutes

Note: These errors are usually temporary and resolve within a few minutes.

PreviousGet Account Balance NextWebhook Callback

Last updated 1 day ago