Transactions - MX Documentation

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

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

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.

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

"action","id","user_id","member_id","account_id","amount","description","posted_on","status","transacted_on"
"upsert","T-1234-10112024","U-39XBF7","M-39XBF7","A-1234-Chk",12.00,"POS Walmart Pharmacy","2024-10-11","POSTED","2024-10-11"
"upsert","T-4567-10122024","U-39XBF7","M-39XBF7","A-1234-Chk",150.00,"Transfer to Savings",,"PENDING","2024-10-12"

​Transaction Fields

​Transaction File Parameters

​Sample File

Transaction Fields

Transaction File Parameters

Sample File