List Transactions
Example URL: https://mdx.yourdomain.com/acme/accounts/0034/transactions?start_date=2013-06-07&page=1
Transactions are retrieved by making an GET request to /accounts/{account_id}/transactions.
When synchronizing account data, transactions will be requested for each account returned in your GET /accounts response. Transactions are always requested over a given date range. During the first account synchronization, a larger number of days (typically 90) will be requested. During subsequent synchronizations, a smaller number of days of transactions (typically 15) will be requested. All transactions that exist in the specified date range must be returned in order to ensure synchronization works properly.
If the provided account_id is invalid, a 404 Not Found error response should be returned.
If the requested date range contains no transactions, an empty or self-terminating <transactions> element (including the required attributes) should be returned.
A success response must contain an <account> element. The <account> element must contain an <id> field and a <transactions> element. Any other account fields will be ignored.
MX Request Query Parameters
| Field | Required | Type |
|---|---|---|
start_date | Required | String |
page | Required | Integer |
Required Attributes of the Response's transactions> Element
| Field | Required | Type |
|---|---|---|
start_date | Required | String |
pages | Required | Integer |
page | Required | Integer |
Response Fields
| Field | Required | Type |
|---|---|---|
amount | Required | Decimal |
category_guid | Optional | String |
category | Optional | String |
check_image | Optional | String |
check_number | Optional | String |
currency_code | Optional | String |
description | Required | String |
id | Required | String |
is_international | Optional | String |
latitude | Optional | String |
localized_description | Optional | String |
localized_memo | Optional | String |
longitude | Optional | String |
memo | Optional | String |
merchant_category_code | Optional | String |
merchant_guid | Optional | String |
merchant_location_guid | Optional | String |
metadata | Optional | String |
posted_at One of either | Required | String |
posted_on One of either | Required | String |
status | Required | String |
transacted_at | Optional | String |
transacted_on | Optional | String |
type | Required | String |
Start Date
The date range of transactions to return is determined by taking the current date and going back to the start date that is passed in the request's query string. The start_date parameter is an ISO 8601 formatted date in YYYY-MM-DD format. The given start date must be returned as an attribute of the transactions list.
The date specified in start_date is based on the posted date, not the transaction date. It's important that all transactions be included that have a posted date on or after the requested start_date. If a transaction has a posted date that differs from the transaction date, it should only be included if the requested range includes the posted date of that transaction, regardless of the transaction date. Pending transactions (for data providers who include them) should be included even though they will not have a posted date.
If a you don't have transactions available that go back to the requested start_date, return what transactions you do have available. However, it should be a full set of transactions back to the earliest posted date that is returned. A partial set of transactions should never be returned.
MX will reconcile the transactions in our system with the transactions received in the list transactions responses for each account. This reconciliation process will insert new transactions, update existing transactions, and remove transactions that are no longer in your data feed.
Reconciliation is done separately for each account. The date range to be reconciled is determined by the posted date values of the transactions received in the response. Reconciliation does not occur if no transactions are provided for an account. All existing transactions in those accounts are left intact.
Pagination
Transaction responses may be paginated when there are more than can conveniently be returned in a single response. Partners can return any number of transactions, but the response must be received in a timely manner. If MX does not receive a response within 60 seconds, the request will time out and the job will be terminated. MX recommends you return no more than 250 transactions per page if your system cannot ensure a timely response with larger numbers of transactions.
MX's request always includes a page parameter on the URL. The response must include page and pages attributes in the <transactions> element. The page attribute will reflect the page being returned. MX always makes a request for page 1. The pages attribute indicates how many pages should be requested. If pages is greater than 1then MX will make requests for the additional pages.
You can cause MX to "break out" of these requests by returning pages=0 in a response. This indicates that the last page has been reached and MX should not request additional pages. For example, if your response to page 1 indicates there will be five pages, MX will normally make additional requests for pages 2 through 5. However, if any of those requests return pages=0, then MX will not make any further page requests. This allows "dynamic paging" where you can signal to MX that there are no more pages even if the initial pages value has not yet been reached.