Transactions

transaction represents a financial transaction in an account in a supported institution. Finicity's Transaction resource includes services for retrieving customer transactions.

See Transaction Types for an explanation of supported transaction types.

See Categorization for an explanation of transaction categorization.

See Active Docs to experiment directly with the API.

Available services:

Transaction Record

The following fields are available in a transaction record:

Field Name Description
accountId The Finicity ID of the account associated with this transaction
amount The total amount of the transaction. Transactions for deposits are positive values, withdrawals and debits are negative values.
bonusAmount The portion of the transaction allocated to bonus, if available
checkNum The check number of the transaction, as provided by the institution
createdDate A timestamp showing when the transaction was added to the Finicity system. (See Handling Dates and Times.) This value usually is not interesting outside of Finicity.
customerId The Finicity ID of the customer associated with this transaction
description The description of the transaction, as provided by the institution (often known as payee)
escrowAmount The portion of the transaction allocated to escrow, if available
feeAmount The portion of the transaction allocated to fee, if available
id The Finicity ID of the transaction
interestAmount The portion of the transaction allocated to interest, if available
memo The memo field of the transaction, as provided by the institution
postedDate A timestamp showing when the transaction was posted or cleared by the institution (see Handling Dates and Times)
principalAmount The portion of the transaction allocated to principal, if available
status One of active, pending, or shadow (see Pending Transactions and Shadow Transactions)
subaccount The subaccount record associated with the transaction (for Corporate Card Aggregation Service only)
transactionDate An optional timestamp showing when the transaction occurred, as provided by the institution (see Handling Dates and Times)
type One of the values from Transaction Types
unitQuantity The number of units (e.g. individual shares) in the transaction, if available
unitValue The value of each unit in the transaction, if available 
categorization The categorization of the transaction.

Pending Transactions

A pending transaction is a transaction that has been initiated but has not been cleared or posted by the institution. For many institutions, Finicity is now able to capture pending transactions when they are displayed or provided in the institution's data.

Pending transactions are ephemeral. Each connection to an institution will capture pending transactions that are available at that time; if any of those transactions are not found in a subsequent connection, they will be deleted from the data. In other words, an account will show the set of pending transactions which were found in the most recent aggregation of the account. Older pending transactions may disappear, and new transactions may appear.

There is no continuity for transactions that move from pending to posted at the institution. When an institution changes a transaction from pending to posted, the pending transaction will disappear in Finicity's data, and a new transaction with status active will appear.

“Pending” transactions are identified in the transaction record, like this:

<transaction>
<amount>-25.99</amount>
<accountId>2055</accountId>
<customerId>41442</customerId>
<status>pending</status>
...
</transaction>

Shadow Transactions

Some institutions continue to modify or delete transactions long after they are first posted to the institution’s data feed. This practice can cause Finicity transactions to appear as duplicates, or to continue to appear in the Finicity data after they have disappeared from the institution’s current website.

Finicity has added the ability to identify transactions that were found in an earlier aggregation of an account, but are not found in the institution’s current data source. These “shadow” transactions are identified in the transaction record, like this:

<transaction>
<amount>-124.99</amount>
<accountId>2055</accountId>
<customerId>41442</customerId>
<status>shadow</status>
...
</transaction>

The client app may choose how to handle shadow transactions. For example, it could choose not to display these transactions at all; to remove them from the app’s data store; to display a button so the customer can confirm that the transaction should be removed; or to ignore the field entirely.

Categorization Record

The following fields are available in a categorization record:

Field Name Description
normalizedPayeeName A normalized payee, derived from the transaction's description and memo fields.
category One of the values from Categories (assigned based on the payee name)
scheduleC One of the values from ScheduleC (assigned based on the payee name)
sic The payee's SIC code

Get Customer Transactions

GET /v3/customers/{customerId}/transactions?fromDate=[timestamp]&toDate=[timestamp]&start=[index]&limit=[count]&sort=[asc or desc]&includePending=[true or false]

Get all transactions available for this customer within the given date range, across all accounts. This service supports paging and sorting by transactionDate (or postedDate if no transaction date is provided), with a maximum of 1000 transactions per request.

Standard consumer aggregation provides up to 180 days of transactions prior to the date each account was added to the Finicity system. To access older transactions, you must first call the Cash Flow Verification service Load Historic Transactions for Account.

There is no limit for the size of the window between fromDate and toDate; however, the maximum number of transactions returned in one page is 1000.

If the value of moreAvailable in the response is true, you can retrieve the next page of results by increasing the value of the start parameter in your next request:

  ...&start=6&limit=5

JSON Implementation

Request Details: 

Parameter Type Default Description
Finicity-App-Key HTTP header   Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header   Token returned from Partner Authentication
Accept HTTP header  

application/xml

customerId path  

The ID of the customer whose transactions are to be retrieved

fromDate query   Starting timestamp for the date range (required) (see Handling Dates and Times)
toDate query   Ending timestamp for the date range (required, must be greater than fromDate) (see Handling Dates and Times
start query 1 Starting index for this page of results
limit query 1000 Maximum number of entries for this page of results (max is 1000)
sort query desc Sort order: asc for ascending order (oldest transactions are on page 1), desc for descending order (newest transactions are on page 1).
includePending query false true to include pending transactions if available.

Success: HTTP 200 (OK)

Example Requests:

GET https://api.finicity.com/aggregation/v3/customers/41442/transactions?fromDate=1417045583&toDate=1422316026
GET https://api.finicity.com/aggregation/v3/customers/41442/transactions?fromDate=1417045583&toDate=1422316026&start=3&limit=2&sort=desc

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -X GET "https://api.finicity.com/aggregation/v3/customers/41442/transactions?fromDate=1417045583&toDate=1422316026&start=3&limit=2&sort=desc"

Response Details:

Field Name Description
found Total number of records matching search criteria
displaying Number of records in this response
moreAvailable true if this response does not contain the last record in the result set
fromDate  Value of the fromDate request parameter that generated this response
toDate Value of the toDate request parameter that generated this response
sort Value of the sort request parameter that generated this response
transactions List of transaction records

Example Response:

{
"found": 250,
"displaying": 2,
"moreAvailable": true,
"fromDate": 1417045583,
"toDate": 1422316026,
"sort": "desc",
"transactions": [
{
"id": 805353,
"amount": -59.56,
"accountId": 98684,
"customerId": 41442,
"status": "active",
"description": "VERIZON WIRELESS PAYMENTS",
"memo": "VERIZON WIRELESS PAYMENTS",
"type": "directDebit",
"postedDate": 1450852000,
"createdDate": 1460621294,
"categorization": {
"normalizedPayeeName": "Verizon Wireless",
"sic": "4813",
"category": "Mobile Phone",
"scheduleC": "Phone"
}
},
{
"id": 805350,
"amount": 647.96,
"accountId": 98689,
"customerId": 41442,
"status": "active",
"description": "Square Inc 168P2",
"memo": "Square Inc 168P2",
"type": "directDeposit",
"postedDate": 1450152000,
"createdDate": 1460621294,
"categorization": {
"normalizedPayeeName": "Deposit Square Type",
"category": "Income",
"scheduleC": "Business Income"
}
}
]
}

XML Implementation

Request Details: 

Parameter Type Default Description
Finicity-App-Key HTTP header   Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header   Token returned from Partner Authentication
Accept HTTP header  

application/xml

customerId path  

The ID of the customer whose transactions are to be retrieved

fromDate query   Starting timestamp for the date range (required) (see Handling Dates and Times)
toDate query   Ending timestamp for the date range (required, must be greater than fromDate) (see Handling Dates and Times
start query 1 Starting index for this page of results
limit query 1000 Maximum number of entries for this page of results (max is 1000)
sort query desc Sort order: asc for ascending order (oldest transactions are on page 1), desc for descending order (newest transactions are on page 1).
includePending query false true to include pending transactions if available.

Success: HTTP 200 (OK)

Example Requests:

GET https://api.finicity.com/aggregation/v3/customers/41442/transactions?fromDate=1417045583&toDate=1422316026
GET https://api.finicity.com/aggregation/v3/customers/41442/transactions?fromDate=1417045583&toDate=1422316026&start=3&limit=2&sort=desc

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/xml" -X GET "https://api.finicity.com/aggregation/v3/customers/41442/transactions?fromDate=1417045583&toDate=1422316026&start=3&limit=2&sort=desc"

Response Details:

XML Name Description
transactions Root element
found Attribute giving the total number of records matching search criteria
displaying Attribute giving the number of records in this response
moreAvailable Attribute giving true if this response does not contain the last record in the result set
fromDate  Attribute giving the value of the fromDate request parameter that generated this response
toDate Attribute giving the value of the toDate request parameter that generated this response
sort Attribute giving the value of the sort request parameter that generated this response
transaction A transaction record

Example Response:

<transactions found="250" displaying="2" moreAvailable="true" fromDate="1417045583" toDate="1422316026" sort="desc">
  <transaction>
<id>805353</id>
<amount>-59.56</amount>
<accountId>98684</accountId>
<customerId>41442</customerId>
<status>active</status>
<description>VERIZON WIRELESS PAYMENTS</description>
<memo>VERIZON WIRELESS PAYMENTS</memo>
<type>directDebit</type>
<postedDate>1450852000</postedDate>
<createdDate>1460621294</createdDate>
<categorization>
<normalizedPayeeName>Verizon Wireless</normalizedPayeeName>
<sic>4813</sic>
<category>Mobile Phone</category>
<scheduleC>Phone</scheduleC>
</categorization>
</transaction>
<transaction>
<id>805350</id>
<amount>647.96</amount>
<accountId>98689</accountId>
<customerId>41442</customerId>
<status>active</status>
<description>Square Inc 168P2</description>
<memo>Square Inc 168P2</memo>
<type>directDeposit</type>
<postedDate>1450152000</postedDate>
<createdDate>1460621294</createdDate>
<categorization>
<normalizedPayeeName>Deposit Square Type</normalizedPayeeName>
<category>Income</category>
<scheduleC>Business Income</scheduleC>
</categorization>
</transaction>
</transactions>

Get Customer Account Transactions

GET /v3/customers/{customerId}/accounts/{accountId}/transactions?fromDate=[timestamp]&toDate=[timestamp]&start=[index]&limit=[count]&sort=[asc or desc]&includePending=[true or false]

Get all transactions available for this customer account within the given date range. This service supports paging and sorting by transactionDate (or postedDate if no transaction date is provided), with a maximum of 1000 transactions per request.

Standard consumer aggregation provides up to 180 days of transactions prior to the date each account was added to the Finicity system. To access older transactions, you must first call the Cash Flow Verification service Load Historic Transactions for Account.

There is no limit for the size of the window between fromDate and toDate; however, the maximum number of transactions returned in one page is 1000.

If the value of moreAvailable in the response is true, you can retrieve the next page of results by increasing the value of the start parameter in your next request:

  ...&start=6&limit=5

JSON Implementation

Request Details: 

Parameter Type Default Description
Finicity-App-Key HTTP header   Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header   Token returned from Partner Authentication
Accept HTTP header  

application/json

customerId path  

The ID of the customer whose transactions are to be retrieved

accountId  path   The ID of the account whose transactions are to be retrieved
fromDate query   Starting timestamp for the date range (required) (see Handling Dates and Times)
toDate query   Ending timestamp for the date range (required, must be greater than fromDate) (see Handling Dates and Times
start query 1 Starting index for this page of results
limit query 1000 Maximum number of entries for this page of results (max is 1000)
sort query desc Sort order: asc for ascending order (oldest transactions are on page 1), desc for descending order (newest transactions are on page 1).
includePending query false true to include pending transactions if available.

Success: HTTP 200 (OK)

Example Requests:

GET https://api.finicity.com/aggregation/v3/customers/41442/accounts/98684/transactions?fromDate=1417045583&toDate=1422316026
GET https://api.finicity.com/aggregation/v3/customers/41442/accounts/98684/transactions?fromDate=1417045583&toDate=1422316026&start=3&limit=2&sort=desc

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -X GET "https://api.finicity.com/aggregation/v3/customers/41442/accounts/98684/transactions?fromDate=1417045583&toDate=1422316026&start=3&limit=2&sort=desc"

Response Details:

Field Name Description
found Total number of records matching search criteria
displaying Number of records in this response
moreAvailable true if this response does not contain the last record in the result set
fromDate  Value of the fromDate request parameter that generated this response
toDate Value of the toDate request parameter that generated this response
sort Value of the sort request parameter that generated this response
transactions List of transaction records

Example Response:

{
"found": 63,
"displaying": 2,
"moreAvailable": true,
"fromDate": 1417045583,
"toDate": 1422316026,
"sort": "desc",
"transactions": [
{
"id": 805353,
"amount": -59.56,
"accountId": 98684,
"customerId": 41442,
"status": "active",
"description": "VERIZON WIRELESS PAYMENTS",
"memo": "VERIZON WIRELESS PAYMENTS",
"type": "directDebit",
"postedDate": 1450852000,
"createdDate": 1460621294,
"categorization": {
"normalizedPayeeName": "Verizon Wireless",
"sic": "4813",
"category": "Mobile Phone",
"scheduleC": "Phone"
}
},
{
"id": 805350,
"amount": 647.96,
"accountId": 98689,
"customerId": 41442,
"status": "active",
"description": "Square Inc 168P2",
"memo": "Square Inc 168P2",
"type": "directDeposit",
"postedDate": 1450152000,
"createdDate": 1460621294,
"categorization": {
"normalizedPayeeName": "Deposit Square Type",
"category": "Income",
"scheduleC": "Business Income"
}
}
]
}

XML Implementation

Request Details: 

Parameter Type Default Description
Finicity-App-Key HTTP header   Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header   Token returned from Partner Authentication
Accept HTTP header  

application/xml

customerId path  

The ID of the customer whose transactions are to be retrieved

accountId path   The ID of the account whose transactions are to be retrieved
fromDate query   Starting timestamp for the date range (required) (see Handling Dates and Times)
toDate query   Ending timestamp for the date range (required, must be greater than fromDate) (see Handling Dates and Times
start query 1 Starting index for this page of results
limit query 1000 Maximum number of entries for this page of results (max is 1000)
sort query desc Sort order: asc for ascending order (oldest transactions are on page 1), desc for descending order (newest transactions are on page 1).
includePending query false true to include pending transactions if available.

Success: HTTP 200 (OK)

Example Requests:

GET https://api.finicity.com/aggregation/v3/customers/41442/accounts/98684/transactions?fromDate=1417045583&toDate=1422316026
GET https://api.finicity.com/aggregation/v3/customers/41442/accounts/98684/transactions?fromDate=1417045583&toDate=1422316026&start=3&limit=2&sort=desc

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/xml" -X GET "https://api.finicity.com/aggregation/v3/customers/41442/accounts/98684/transactions?fromDate=1417045583&toDate=1422316026&start=3&limit=2&sort=desc"

Response Details:

XML Name Description
transactions Root element
found Attribute giving the total number of records matching search criteria
displaying Attribute giving the number of records in this response
moreAvailable Attribute giving true if this response does not contain the last record in the result set
fromDate  Attribute giving the value of the fromDate request parameter that generated this response
toDate Attribute giving the value of the toDate request parameter that generated this response
sort Attribute giving the value of the sort request parameter that generated this response
transaction A transaction record

Example Response:

<transactions found="63" displaying="2" moreAvailable="true" fromDate="1417045583" toDate="1422316026" sort="desc">
<transaction>
<id>805353</id>
<amount>-59.56</amount>
<accountId>98684</accountId>
<customerId>41442</customerId>
<status>active</status>
<description>VERIZON WIRELESS PAYMENTS</description>
<memo>VERIZON WIRELESS PAYMENTS</memo>
<type>directDebit</type>
<postedDate>1450852000</postedDate>
<createdDate>1460621294</createdDate>
<categorization>
<normalizedPayeeName>Verizon Wireless</normalizedPayeeName>
<sic>4813</sic>
<category>Mobile Phone</category>
<scheduleC>Phone</scheduleC>
</categorization>
</transaction>
<transaction>
<id>805350</id>
<amount>647.96</amount>
<accountId>98689</accountId>
<customerId>41442</customerId>
<status>active</status>
<description>Square Inc 168P2</description>
<memo>Square Inc 168P2</memo>
<type>directDeposit</type>
<postedDate>1450152000</postedDate>
<createdDate>1460621294</createdDate>
<categorization>
<normalizedPayeeName>Deposit Square Type</normalizedPayeeName>
<category>Income</category>
<scheduleC>Business Income</scheduleC>
</categorization>
</transaction>
</transactions>

Get Customer Transaction

GET /v2/customers/{customerId}/transactions/{transactionId}

Get details for the specified transaction.

JSON Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header

application/json

customerId path

The ID of the customer whose transactions are to be retrieved

transactionId path

The ID of the transaction to be retrieved

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v2/customers/41442/transactions/805350

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -X GET "https://api.finicity.com/aggregation/v2/customers/41442/transactions/805350"

Response Details:

A single transaction record.

Example Response:

{
"id": 805350,
"amount": 647.96,
"accountId": 98689,
"customerId": 41442,
"status": "active",
"description": "Square Inc 168P2",
"memo": "Square Inc 168P2",
"type": "directDeposit",
"postedDate": 1450152000,
"createdDate": 1460621294,
"categorization": {
"normalizedPayeeName": "Deposit Square Type",
"category": "Income",
"scheduleC": "Business Income"
}
}

XML Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header

application/xml

customerId path

The ID of the customer whose transactions are to be retrieved

transactionId path

The ID of the transaction to be retrieved

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v2/customers/41442/transactions/805350

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/xml -X GET "https://api.finicity.com/aggregation/v2/customers/41442/transactions/805350"

Response Details:

An XML document containing one transaction record.

Example Response:

<transaction>
<id>805350</id>
<amount>647.96</amount>
<accountId>98689</accountId>
<customerId>41442</customerId>
<status>active</status>
<description>Square Inc 168P2</description>
<memo>Square Inc 168P2</memo>
<type>directDeposit</type>
<postedDate>1450152000</postedDate>
<createdDate>1460621294</createdDate>
<categorization>
<normalizedPayeeName>Deposit Square Type</normalizedPayeeName>
<category>Income</category>
<scheduleC>Business Income</scheduleC>
</categorization>
</transaction>
Have more questions? Submit a request

Comments

Powered by Zendesk