Transactions

Transaction files are for creating and updating transactions that are managed by your institution for your users.

caution

All date fields ending with _on are expected as an ISO 8601 formatted date only with no timestamp (for example, 2024-04-20).

Transaction Fields

Field	Data Type (Max)	Description
account_guid	String	The unique identifier for the account this transaction belongs to. Defined by MX.
account_id	String	The unique partner-defined identifier for the account this transaction belongs to.
amount	Decimal	The amount is always unsigned. The type will determine how the transaction affects the account. Max length is 10,2. See Number Limits.
category_guid	String	The unique identifier for the transaction category. Defined by MX.
category_name	String	The transaction category given as a human-readable string. This may be null in a response.
category	String	The transaction category given as an enumerated value. This may be null in a response. If provided with a create or update request, it will be ignored if not valid for the user. If not provided with a create or update request, MX will categorize the transaction automatically. See Default Categories for a list of all transaction categories.
check_number	String	The check number.
currency_code	String	The ISO 4217 three-character currency code.
description	String	A human-readable description of the transaction. Max length is 1024. Warning: Unescaped XML or JSON characters will a Real Time integration. See Escaped Characters for more information.
guid	String	The unique identifier for the transaction. Defined by MX.
id	String	The unique partner-defined identifier for the transaction. The id can't begin with TRN- as this is reserved for the system. It must be unique for all transactions belonging to an account as it's used for matching purposes. Transactions should always be returned with the same ID, even if transactional information has changed (type, amount, description, dates) since the previous account synchronization. It's permissible for the transaction ID to change when a transaction changes from PENDING to POSTED status if the previous transaction ID can't be maintained. It can include numbers, letters, dash, and underscore. Max Length is 1024.
is_international	Boolean	This indicates whether the transaction is international, as determined by the data provider. Defaults to null when not provided. This field should only be set to true or false if the value is explicitly known by the data provider. Otherwise it should be omitted or set to null.
latitude	Decimal	The latitude of the location where the transaction occurred. The number is a signed decimal (e.g. Rio de Janeiro's latitude is -22.9027800 and Tokyo's latitude is 35.689488).
localized_description	String	A human-readable description of the transaction, provided in a local language.
localized_memo	String	Additional descriptive information about the transaction, provided in a local language.
longitude	Decimal	The longitude of the location where the transaction occurred. The number is a signed decimal (e.g. Rio de Janeiro's longitude is -43.2075000 and Tokyo's longitude is 139.691706).
member_guid	String	The unique identifier for the member. Defined by MX.
member_id	String	The unique partner-defined identifier for the member.
memo	String	The memo is additional descriptive information about the transaction. Max length is 1024.
merchant_category_code	String	The merchant category code.
merchant_guid	String	The unique identifier for the merchant associated with the transaction. Defined by MX.
merchant_location_guid	String	The unique identifier for the merchant location associated with the transaction. Defined by MX.
metadata	String	Additional information you can store on the transaction.
posted_at	Integer	The date and time the transaction was posted. You're required to apply any applicable timezone offset to ensure Unix Epoch values are UTC-based. Each transaction is required to have a valid date for either posted_at or posted_on if the status is POSTED. Optional if the status is PENDING.
posted_on	String	The date the transaction was posted. Each transaction is required to have a valid date for either posted_at or posted_on if the status is POSTED. Optional if the status is PENDING.
running_balance	Decimal	The available balance of the related account at the time this transaction was posted. This field is only viable for transactions in the POSTED state. Max length is 14,2. See Number Limits.
status	String	One of PENDING or POSTED. A read request might contain a null status.
transacted_at	Integer	The date and time the transaction took place. You're required to apply any applicable timezone offset to ensure Unix Epoch values are UTC-based. Each transaction is required to have a valid date for either transacted_at or transacted_on.
transacted_on	String	The date the transaction took place. Each transaction is required to have a valid date for either transacted_at or transacted_on.
type	String	One of DEBIT or CREDIT. A CREDIT increases the user's net worth. A DEBIT decreases the user's net worth. This applies to all account types.
user_guid	String	The unique identifier for the user the transaction belongs to. Defined by MX.
user_id	String	The unique partner-defined identifier for the user associated with the transaction.

Transaction File Parameters

note

The action field tells us what data operation to perform for each row in the file. Options are upsert (an insert/update depending on if the object already exists) and delete (which will destroy the record). If no action is provided the default action is upsert.

note

The skip_webhook parameter prevents a webhook being sent for the action effected by each row. Accepted values are true or false. If skip_webhook is not provided, MX will default to your internal batch configuration setting.

Field	Required for Upsert?	Required for Delete?	Type
id	Yes	Yes	String
user_id	Yes	Yes	String
member_id	Yes	Yes	String
account_id	Yes	Yes	String
action	Yes	No	String
amount	Yes	No	Decimal
description	Yes	No	String
posted_at (One of either posted_at or posted_on is required)	Yes	No	String
posted_on (One of either posted_at or posted_on is required)	Yes	No	String
status	Yes	No	String
transacted_at (One of either transacted_at or transacted_on is required)	Yes	No	String
transacted_on (One of either transacted_at or transacted_on is required)	Yes	No	String
type	Yes	No	String
currency_code	No	No	String
is_international	No	No	String
latitude	No	No	String
longitude	No	No	String
memo	No	No	String
merchant_category_code	No	No	String
metadata	No	No	String
skip_webhooks	No	No	Boolean

Sample File

The following is a sample Transactions batch CSV file.

CSV

Language:text

_10

"action","id","user_id","member_id","account_id","amount","description","posted_on","status","transacted_on"

_10

"upsert","T-1234-10112024","U-39XBF7","M-39XBF7","A-1234-Chk",12.00,"POS Walmart Pharmacy","2024-10-11","POSTED","2024-10-11"

_10

"upsert","T-4567-10122024","U-39XBF7","M-39XBF7","A-1234-Chk",150.00,"Transfer to Savings",,"PENDING","2024-10-12"