Get last Financial account activity

post

https://api.banking.netevia.dev/api/transaction/v3/byFinancialAccount/server

Get Last Financial Account Activity

The POST /api/transaction/v3/byFinancialAccount/server endpoint retrieves a filtered and paginated list of the most recent transactions for a specified financial account. It supports date range filtering, transaction type filtering, amount range filtering, and keyword search to help partners surface relevant account activity. Results include full transaction details such as status, amounts, merchant data, card identifiers, and transfer metadata.

Endpoint

POST /api/transaction/v3/byFinancialAccount/server

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint to display a customer's transaction history within your application, including account statements, activity feeds, and balance reconciliation views. It is suitable for both business and personal customer contexts where you need to present recent account activity with flexible filtering. The server-side variant is intended for backend integrations that need to query transactions on behalf of a customer without direct client involvement.

Request Body

The request body accepts one of two schemas. The base schema (financialaccountwithperiodandamountfilterrequest) is the standard form. The extension (financialaccountwithperiodandamountfilterrequestextension) adds an optional override for financialAccountId.

All fields from the inheritance chain are listed below:

Field	Type	Required	Description
`financialAccountId`	string	Yes	The unique identifier of the financial account to query.
`dateFrom`	string (date-time)	Yes	Start of the date range for the transaction query (ISO 8601).
`dateTo`	string (date-time)	Yes	End of the date range for the transaction query (ISO 8601).
`amountFilter`	object	No	Optional amount range filter (see `amountFilter` fields below).
`amountFilter.minValue`	integer (int64)	No	Minimum transaction amount in the smallest currency unit (e.g., cents).
`amountFilter.maxValue`	integer (int64)	No	Maximum transaction amount in the smallest currency unit (e.g., cents).
`searchString`	string	No	Free-text keyword to search within transaction descriptions or merchant names.
`filter`	object	No	Structured transaction type filter (see `filter` fields below).
`filter.all`	object (filterItem)	No	Include all transaction types.
`filter.deposit`	object (filterItem)	No	Filter for deposit transactions.
`filter.withdraw`	object (filterItem)	No	Filter for withdrawal transactions.
`filter.transfers`	object (filterItem)	No	Filter for transfer transactions.
`filter.pos`	object (filterItem)	No	Filter for point-of-sale transactions.
`filter.transactionStatus`	object (filterItem)	No	Filter by transaction status.
`filter.others`	object (filterItem)	No	Filter for other transaction types.
`jsonFilter`	string	No	Raw JSON filter string for advanced filtering scenarios.
`spendEvents`	array of string	No	List of specific spend event types to include.
`paymentCardId`	string	No	Filter transactions by a specific payment card identifier.
`status`	string (enum)	No	Filter by transaction status. One of: `OTHER`, `PENDING`, `COMPLETED`, `FAILED`.
`paginationSettings`	object	No	Pagination controls (see fields below).
`paginationSettings.take`	integer (int32)	No	Number of records to return. Range: 1–10000.
`paginationSettings.skip`	integer (int32)	No	Number of records to skip. Range: 0–2147483647.

{
  "financialAccountId": "fa_abc123def456",
  "dateFrom": "2026-05-01T00:00:00Z",
  "dateTo": "2026-06-01T00:00:00Z",
  "amountFilter": {
    "minValue": 100,
    "maxValue": 50000
  },
  "searchString": "coffee",
  "status": "COMPLETED",
  "filter": {
    "pos": {
      "displayName": "Point of Sale",
      "value": true
    }
  },
  "paginationSettings": {
    "take": 25,
    "skip": 0
  }
}

Response

200 OK

Field	Type	Description
`data`	array	List of financial activity records matching the query.
`data[].id`	string	Unique identifier for the activity record.
`data[].financialAccountId`	string	Financial account the activity belongs to.
`data[].date`	string (date-time)	Date and time of the transaction.
`data[].sortDate`	string (date-time)	Date used for sorting the activity.
`data[].balance`	object	Account balance after the transaction (`value` in cents, `currencyCode`).
`data[].status`	string (enum)	Transaction status: `OTHER`, `PENDING`, `COMPLETED`, `FAILED`.
`data[].riskHold`	boolean	Whether the transaction is on a risk hold.
`data[].settlementDate`	string (date-time)	Date the transaction settled, if applicable.
`data[].purpose`	string	Stated purpose or memo for the transaction.
`data[].statusReasonCode`	string	Machine-readable reason code for the current status.
`data[].amount`	object	Transaction amount (`value` in cents, `currencyCode`, `symbol`).
`data[].clearAmount`	object	Cleared amount (`value`, `currencyCode`, `symbol`).
`data[].pendingAmount`	object	Pending portion of the transaction amount (`value`, `currencyCode`).
`data[].name`	string	Display name or description of the transaction.
`data[].last4`	object	Last 4 digits context: `type` (`CARD` or `ACCOUNT`) and `value`.
`data[].type`	string	Transaction type label (read-only).
`data[].authorizedUser`	string	Name or identifier of the authorized user who made the transaction.
`data[].merchantCategory`	string	Merchant category label.
`data[].rewardPoints`	integer (int64)	Reward points earned on this transaction, if applicable.
`data[].transactionSource`	object	Source transaction reference: `typename`, `id`, and `transactionEvents` array.
`data[].activityInfo`	object	Activity metadata: `fromProfile`, `toProfile`, and `historyRecords`.
`data[].financialEvent`	object	Detailed financial event data including merchant details, card info, amounts, ACH fields, and response codes.
`filter`	object	Echo of the transaction type filter applied to the query.
`paginationResponse`	object	Pagination metadata.
`paginationResponse.totalItems`	integer (int32)	Total number of records matching the query before pagination.

{
  "data": [
    {
      "id": "evt_9f8e7d6c5b4a",
      "financialAccountId": "fa_abc123def456",
      "date": "2026-05-28T14:32:00Z",
      "sortDate": "2026-05-28T14:32:00Z",
      "balance": {
        "value": 245000,
        "currencyCode": "USD"
      },
      "status": "COMPLETED",
      "riskHold": false,
      "settlementDate": "2026-05-29T00:00:00Z",
      "purpose": "PURCHASE",
      "statusReasonCode": null,
      "amount": {
        "value": 1250,
        "currencyCode": "USD",
        "symbol": "$"
      },
      "clearAmount": {
        "value": 1250,
        "currencyCode": "USD",
        "symbol": "$"
      },
      "pendingAmount": {
        "value": 0,
        "currencyCode": "USD"
      },
      "name": "Blue Bottle Coffee",
      "last4": {
        "type": "CARD",
        "value": "4321"
      },
      "type": "CARD_TRANSACTION",
      "authorizedUser": null,
      "merchantCategory": "Restaurants",
      "rewardPoints": 12,
      "transactionSource": {
        "typename": "CardTransaction",
        "id": "txn_1a2b3c4d",
        "transactionEvents": [
          {
            "typename": "CardAuthorization",
            "id": "auth_5e6f7g8h",
            "merchantDetails": {
              "category": "Eating Places, Restaurants",
              "categoryCode": "5812",
              "countryCodeAlpha3": "USA",
              "description": "Coffee Shop",
              "name": "Blue Bottle Coffee",
              "merchantId": "mid_xyz789"
            },
            "pointOfServiceDetails": {
              "panEntryMode": "CHIP",
              "pinEntryMode": "NOT_A_PIN_TRANSACTION"
            },
            "responseCode": "APPROVED",
            "responseDescription": "Approved",
            "approvedAmount": {
              "value": 1250,
              "currencyCode": "USD"
            },
            "requestedAmount": {
              "value": 1250,
              "currencyCode": "USD"
            },
            "paymentCard": {
              "id": "pc_card001",
              "bin": "411111",
              "last4": "4321"
            },
            "createdAt": "2026-05-28T14:32:00Z",
            "authorizationExpiration": "2026-06-04T14:32:00Z",
            "processingType": "DUAL_MESSAGE",
            "rewardPoints": 12,
            "accountingDirection": "DEBIT"
          }
        ]
      },
      "activityInfo": null,
      "financialEvent": null
    }
  ],
  "filter": {
    "pos": {
      "displayName": "Point of Sale",
      "value": true
    }
  },
  "paginationResponse": {
    "totalItems": 1
  }
}

Error Codes

Code	When it happens
400	Missing required fields (`financialAccountId`, `dateFrom`, or `dateTo`), invalid date format, or `take` value out of range (1–10000)
401	Token missing, expired, or invalid
403	Insufficient permissions to access the specified financial account
404	Financial account not found
500	Internal server error

Common Mistakes

Omitting financialAccountId, dateFrom, or dateTo — all three are required fields; the request will fail with a 400 error.
Providing dates outside ISO 8601 date-time format — use the YYYY-MM-DDTHH:MM:SSZ format consistently for dateFrom and dateTo.
Setting paginationSettings.take to 0 or above 10000 — the allowed range is 1 to 10000; values outside this range will cause a validation error.
Using amountFilter values in dollars instead of cents — all monetary amounts are expressed in the smallest currency unit (e.g., 1250 represents $12.50 USD).
Querying a financialAccountId that belongs to a different customer profile — the token's partner scope must have access to the target account.

Related Endpoints

POST /api/transaction/v3/byFinancialAccount — Client-facing variant for retrieving financial account activity.
GET /api/financialaccount/v2/{financialAccountId} — Retrieve details and current balance for a specific financial account.
POST /api/financialaccount/v2/list — List all financial accounts associated with a customer profile.

Example

curl -X POST https://api.banking.netevia.dev/api/transaction/v3/byFinancialAccount/server \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "financialAccountId": "fa_abc123def456",
    "dateFrom": "2026-05-01T00:00:00Z",
    "dateTo": "2026-06-01T00:00:00Z",
    "amountFilter": {
      "minValue": 100,
      "maxValue": 50000
    },
    "searchString": "coffee",
    "status": "COMPLETED",
    "paginationSettings": {
      "take": 25,
      "skip": 0
    }
  }'

Body Params

amountFilter

object

searchString

string | null

filter

object

jsonFilter

string | null

spendEvents

array of strings | null

spendEvents

paymentCardId

string | null

status

string

enum

Allowed:

paginationSettings

object

dateFrom

date-time

required

dateTo

date-time

required

financialAccountId

string

required

length ≥ 1

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

content-type

string

enum

Defaults to application/json

Generated from available request content types

Allowed:

Response

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

text/plain

application/json

text/json