Read transaction

curl --request GET \
  --url https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid} \
  --header 'Accept-Version: <accept-version>' \
  --header 'Authorization: Basic <encoded-value>'

import requests

url = "https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid}"

headers = {
    "Accept-Version": "<accept-version>",
    "Authorization": "Basic <encoded-value>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Accept-Version': '<accept-version>', Authorization: 'Basic <encoded-value>'}
};

fetch('https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Accept-Version: <accept-version>",
    "Authorization: Basic <encoded-value>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept-Version", "<accept-version>")
	req.Header.Add("Authorization", "Basic <encoded-value>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid}")
  .header("Accept-Version", "<accept-version>")
  .header("Authorization", "Basic <encoded-value>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept-Version"] = '<accept-version>'
request["Authorization"] = 'Basic <encoded-value>'

response = http.request(request)
puts response.read_body

{
  "transaction": {
    "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
    "account_id": "account123",
    "amount": 61.11,
    "category": "Paycheck",
    "category_guid": "CAT-b6d61a19-30a7-e852-2703-bdfb4072289e",
    "check_number_string": null,
    "created_at": "2025-02-13T18:08:00+00:00",
    "currency_code": "USD",
    "date": "2024-12-20",
    "description": "MX Technologies Payroll",
    "extended_transaction_type": null,
    "guid": "TRN-429ad9fe-a1d2-4559-8590-885b2603f0e1",
    "id": "1734681600000-178fa8095c154a55b9172f977b4c5f9a-0",
    "is_bill_pay": false,
    "is_direct_deposit": false,
    "is_expense": false,
    "is_fee": false,
    "is_income": true,
    "is_international": false,
    "is_manual": false,
    "is_overdraft_fee": false,
    "is_payroll_advance": false,
    "is_recurring": null,
    "is_subscription": false,
    "latitude": null,
    "localized_description": "This is a localized_description",
    "localized_memo": "This is a localized_memo",
    "longitude": null,
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "member_is_managed_by_user": true,
    "memo": "Transactions",
    "merchant_category_code": null,
    "merchant_guid": "MCH-8cc3b01a-1c52-47d4-970d-30f8ee5566f1",
    "merchant_location_guid": null,
    "metadata": "some metadata",
    "original_description": "MX TECHNOLOGIES PAYMENT",
    "posted_at": "2024-12-20T12:00:00Z",
    "status": "POSTED",
    "top_level_category": "Income",
    "transacted_at": "2024-12-20T12:00:00Z",
    "type": "CREDIT",
    "updated_at": "2025-02-13T18:09:00+00:00",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "u-1234",
    "classification": {
      "parent_class": "Deposit",
      "guid": "MNC-3ad50f86-60d0-4545-a1f9-e66c2ac40f69"
    },
    "geolocation": {
      "country": "US",
      "state": "UT",
      "city": "North Kishaberg",
      "postal code": "84043"
    },
    "merchant": {
      "name": "MX",
      "guid": "MCH-0c25f895-393c-42a4-9c18-95a0b26d4d84",
      "logo_url": "https://content.mx.com/logos/merchants/MCH-0c25f895-393c-42a4-9c18-95a0b26d4d84.png",
      "website_url": "https://www.example.com"
    },
    "repeating_transaction": {
      "repeating_transaction_type": "BILL",
      "recurrence_type": "EVERY_OTHER_WEEK",
      "guid": "RPT-065b8b1d-826a-45ce-8487-60ca1510e72a"
    }
  }
}

Transactions

Read transaction

Requests to this endpoint will return the attributes of the specified transaction. To read a manual transaction, use the manual transaction guid in the path as the transactionGuid.

Enhanced transaction data may be requested using the includes parameter. To use this optional parameter, the value should include the optional metadata requested such as repeating_transactions, merchants, classifications, geolocations. For more information, see the Optional Enhancement Query Parameter guide.

GET

users

{user_guid}

transactions

{transaction_guid}

Read transaction

curl --request GET \
  --url https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid} \
  --header 'Accept-Version: <accept-version>' \
  --header 'Authorization: Basic <encoded-value>'

import requests

url = "https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid}"

headers = {
    "Accept-Version": "<accept-version>",
    "Authorization": "Basic <encoded-value>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Accept-Version': '<accept-version>', Authorization: 'Basic <encoded-value>'}
};

fetch('https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Accept-Version: <accept-version>",
    "Authorization: Basic <encoded-value>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept-Version", "<accept-version>")
	req.Header.Add("Authorization", "Basic <encoded-value>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid}")
  .header("Accept-Version", "<accept-version>")
  .header("Authorization", "Basic <encoded-value>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://int-api.mx.com/users/{user_guid}/transactions/{transaction_guid}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept-Version"] = '<accept-version>'
request["Authorization"] = 'Basic <encoded-value>'

response = http.request(request)
puts response.read_body

{
  "transaction": {
    "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
    "account_id": "account123",
    "amount": 61.11,
    "category": "Paycheck",
    "category_guid": "CAT-b6d61a19-30a7-e852-2703-bdfb4072289e",
    "check_number_string": null,
    "created_at": "2025-02-13T18:08:00+00:00",
    "currency_code": "USD",
    "date": "2024-12-20",
    "description": "MX Technologies Payroll",
    "extended_transaction_type": null,
    "guid": "TRN-429ad9fe-a1d2-4559-8590-885b2603f0e1",
    "id": "1734681600000-178fa8095c154a55b9172f977b4c5f9a-0",
    "is_bill_pay": false,
    "is_direct_deposit": false,
    "is_expense": false,
    "is_fee": false,
    "is_income": true,
    "is_international": false,
    "is_manual": false,
    "is_overdraft_fee": false,
    "is_payroll_advance": false,
    "is_recurring": null,
    "is_subscription": false,
    "latitude": null,
    "localized_description": "This is a localized_description",
    "localized_memo": "This is a localized_memo",
    "longitude": null,
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "member_is_managed_by_user": true,
    "memo": "Transactions",
    "merchant_category_code": null,
    "merchant_guid": "MCH-8cc3b01a-1c52-47d4-970d-30f8ee5566f1",
    "merchant_location_guid": null,
    "metadata": "some metadata",
    "original_description": "MX TECHNOLOGIES PAYMENT",
    "posted_at": "2024-12-20T12:00:00Z",
    "status": "POSTED",
    "top_level_category": "Income",
    "transacted_at": "2024-12-20T12:00:00Z",
    "type": "CREDIT",
    "updated_at": "2025-02-13T18:09:00+00:00",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "u-1234",
    "classification": {
      "parent_class": "Deposit",
      "guid": "MNC-3ad50f86-60d0-4545-a1f9-e66c2ac40f69"
    },
    "geolocation": {
      "country": "US",
      "state": "UT",
      "city": "North Kishaberg",
      "postal code": "84043"
    },
    "merchant": {
      "name": "MX",
      "guid": "MCH-0c25f895-393c-42a4-9c18-95a0b26d4d84",
      "logo_url": "https://content.mx.com/logos/merchants/MCH-0c25f895-393c-42a4-9c18-95a0b26d4d84.png",
      "website_url": "https://www.example.com"
    },
    "repeating_transaction": {
      "repeating_transaction_type": "BILL",
      "recurrence_type": "EVERY_OTHER_WEEK",
      "guid": "RPT-065b8b1d-826a-45ce-8487-60ca1510e72a"
    }
  }
}

Authorizations

Authorization

string

header

required

To authenticate with the Platform API, include your Base64-encoded client_id and api_key in the Authorization header of every request: -H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}'

Headers

Accept-Version

string

default:v20250224

required

MX Platform API version.

Example:

"v20250224"

Path Parameters

user_guid

string

required

The unique identifier for a user, beginning with the prefix USR-.

transaction_guid

string

required

The unique id for a transaction.

Query Parameters

includes

string

Options for enhanced transactions. This query parameter is optional. Possible additional metadata: repeating_transactions, merchants, classifications, geolocations. The query value is format sensitive. To retrieve all available enhancements, append:

?includes=repeating_transactions,merchants,classifications,geolocations.

The query options may be combined to specific enhancements. For example, to request Repeating Transactions and Geolocation data, use:

?includes=repeating_transactions,geolocations.

Repeating Transactions: Identifies transactions with predictable recurrence patterns (e.g., Bill, Income, Subscription).
Merchants: Enriches transactions with merchant name.
Classifications: Provides more insight into the type of money movement that is occurring on the transaction, whether it be retail or investments.
Geolocation: Provides geographic metadata.

Response

200 - application/json

transaction

object

Hide child attributes

transaction.account_guid

string

The unique identifier for an account. Defined by MX.

Example:

"ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1"

transaction.account_id

string | null

The unique client-defined identifier for the account.

Example:

"account123"

transaction.amount

number | null

The monetary amount of the transaction.

Example:

61.11

transaction.category

string | null

The category of the transaction.

Example:

"Paycheck"

transaction.category_guid

string | null

The unique identifier for the category. Defined by MX.

Example:

"CAT-b6d61a19-30a7-e852-2703-bdfb4072289e"

transaction.check_number_string

string | null

The check number for the transaction.

Example:

null

transaction.created_at

string | null

The date and time the transaction was created, represented in ISO 8601 format with a timestamp.

Example:

"2025-02-13T18:08:00+00:00"

transaction.currency_code

string | null

The three-character ISO 4217 currency code, for example, USD.

Example:

"USD"

transaction.date

string | null

The date on which the transaction took place. This is the field used when searching for transactions by date and is generally the same as transacted_at, but uses posted_at as a fallback.

Example:

"2024-12-20"

transaction.description

string | null

A human-readable description of the transaction.

Example:

"MX Technologies Payroll"

transaction.extended_transaction_type

string | null

The transaction type assigned by the partner.

Example:

null

transaction.guid

string | null

The unique identifier for the transaction. Defined by MX.

Example:

"TRN-429ad9fe-a1d2-4559-8590-885b2603f0e1"

transaction.id

string | null

The unique partner-defined identifier for the transaction.

Example:

"1734681600000-178fa8095c154a55b9172f977b4c5f9a-0"

transaction.is_bill_pay

boolean | null

Indicates whether the transaction is a bill payment.

Example:

false

transaction.is_direct_deposit

boolean | null

Indicates whether the transaction is a direct deposit.

Example:

false

transaction.is_expense

boolean | null

Indicates whether the transaction is an expense.

Example:

false

transaction.is_fee

boolean | null

Indicates whether the transaction is a fee.

Example:

false

transaction.is_income

boolean | null

Indicates whether the transaction is income.

Example:

true

transaction.is_international

boolean

Indicates whether the transaction is international. If the data provider determines it isn't international then it will be false. It will be null if the data provider does not have this information.

Example:

false

transaction.is_manual

boolean | null

Indicates whether the transaction was manually created or belongs to a manual account.

Example:

false

transaction.is_overdraft_fee

boolean | null

Indicates whether the transaction is an overdraft fee.

Example:

false

transaction.is_payroll_advance

boolean | null

Indicates whether the transaction is a payroll advance.

Example:

false

transaction.is_recurring

boolean | null

Deprecated. If required, reach out to MX to discuss an alternative.

Example:

null

transaction.is_subscription

boolean | null

Indicates whether the transaction is a subscription payment.

Example:

false

transaction.latitude

number | null

The latitude of the location where the transaction occurred. The number is a signed decimal.

Example:

null

transaction.localized_description

string | null

A human-readable description of the transaction, provided in a local language.

Example:

"This is a localized_description"

transaction.localized_memo

string | null

Additional descriptive information about the transaction, provided in a local language.

Example:

"This is a localized_memo"

transaction.longitude

number | null

The longitude of the location where the transaction occurred. The number is a signed decimal.

Example:

null

transaction.member_guid

string | null

The unique identifier for the member. Defined by MX.

Example:

"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b"

transaction.member_is_managed_by_user

boolean | null

This indicates whether the member is managed by the user or the MX partner. Members created with the managed member feature will have this field set to false.

Example:

true

transaction.memo

string | null

Additional information about the transaction.

Example:

"Transactions"

transaction.merchant_category_code

integer | null

The ISO 18245 category code for the transaction.

Example:

null

transaction.merchant_guid

string | null

The unique identifier for the merchant. Defined by MX.

Example:

"MCH-8cc3b01a-1c52-47d4-970d-30f8ee5566f1"

transaction.merchant_location_guid

string | null

The unique identifier for the merchant location. Defined by MX.

Example:

null

transaction.metadata

string | null

Additional information you stored about the transaction.

Example:

"some metadata"

transaction.original_description

string | null

The original description of the transaction as provided by our data feed.

Example:

"MX TECHNOLOGIES PAYMENT"

transaction.posted_at

string | null

The date and time the transaction was posted to the account.

Example:

"2024-12-20T12:00:00Z"

transaction.status

enum<string> | null

The status of the transaction.

All transaction data on our systems represent what we get through our data feed which depends what institutions make available for aggregation. Many institutions do not provide data for pending transactions; transactions from those accounts always have a status of POSTED.

When we do receive data for pending transactions, a single transaction may be updated from PENDING to POSTED and keep the same guid. This is done through various matching methods performed automatically by MX.

If a single transaction can't be updated, the PENDING transaction will often be deleted and replaced with a new POSTED transaction (with a new guid) when it is sent to us; this is the most common scenario when pending data is available.

In unusual circumstances, there may be separate PENDING and POSTED transactions on MX systems for up to 14 days. All PENDING transactions are deleted after 14 days as a failsafe.

Available options:

POSTED,

PENDING

Example:

"POSTED"

transaction.top_level_category

string | null

The parent category assigned to this transaction's category.

Example:

"Income"

transaction.transacted_at

string | null

The date and time the transaction took place.

Example:

"2024-12-20T12:00:00Z"

transaction.type

enum<string> | null

The type of transaction.

Available options:

CREDIT,

DEBIT

Example:

"CREDIT"

transaction.updated_at

string | null

The date and time the resource was last updated in ISO 8601 format with a timestamp.

For categories, this field will always be null when is_default is true.

Example:

"2025-02-13T18:09:00+00:00"

transaction.user_guid

string | null

The unique identifier for the user. Defined by MX.

Example:

"USR-fa7537f3-48aa-a683-a02a-b18940482f54"

transaction.user_id

string | null

The unique partner-defined identifier for the user.

Example:

"u-1234"

transaction.classification

object | null

Hide child attributes

transaction.classification.parent_class

enum<string>

Available options:

Payroll,

Deposit,

Savings,

Transfer,

Refunds,

Spend,

Investment,

Buy,

Sell,

Income,

Fees,

Expenses,

Corporate Actions,

Other

Example:

"Deposit"

transaction.classification.guid

string

Example:

"MNC-3ad50f86-60d0-4545-a1f9-e66c2ac40f69"

transaction.geolocation

object | null

Hide child attributes

transaction.geolocation.country

string | null

The country name.

Example:

"US"

transaction.geolocation.state

string

Example:

"UT"

transaction.geolocation.city

string | null

The city name.

Example:

"North Kishaberg"

transaction.geolocation.postal code

string

Example:

"84043"

transaction.merchant

object | null

Hide child attributes

transaction.merchant.name

string

The name of the merchant.

Example:

"MX"

transaction.merchant.guid

string

Example:

"MCH-0c25f895-393c-42a4-9c18-95a0b26d4d84"

transaction.merchant.logo_url

string

The URL for a 100px X 100px logo for the merchant.

Example:

"https://content.mx.com/logos/merchants/MCH-0c25f895-393c-42a4-9c18-95a0b26d4d84.png"

transaction.merchant.website_url

string

URL to the merchant's website.

Example:

"https://www.example.com"

transaction.repeating_transaction

object | null

Hide child attributes

transaction.repeating_transaction.repeating_transaction_type

enum<string>

The type of the repeating transaction.

Available options:

BILL,

SUBSCRIPTION,

INCOME,

UNKNOWN

transaction.repeating_transaction.recurrence_type

enum<string>

The recurrence type of the repeating transaction.

Available options:

EVERY_OTHER_WEEK

transaction.repeating_transaction.guid

string

The unique identifier for the repeating transaction. Defined by MX.

Example:

"RPT-065b8b1d-826a-45ce-8487-60ca1510e72a"