Getting Started

This guide explains how to request an access token and how to retrieve different types of information using the access token. It is intended for processors working with an MX Client that have already received an authorization code.

Before you can begin, access your api_key and processor_id in the Client Dashboard. You also need the authorization_code provided by an MX Client.

1. Request an Access Token

After you have received an authorization_code, request an access_token using the following steps:

Make a POST request to the request an access token endpoint.
In the query string parameters, include the authorization_code as shown in the following request example.
The response returns the access_token as seen in the example response.
You’ll need the access_token to request payment account information.

1
2
3
4
5
curl -L -X POST 'https://int-api.mx.com/payment_processor_token?grant_type=authorization_code&code=AUTH_CODE_GOES_HERE' \
-H 'accept: application/vnd.mx.api.v1+json' \
-u 'payment_processor_id:api_key' \

1
2
3
4
5
6
{
    "access_token": "ACCESS_TOKEN_IS_HERE",
    "token_type": "bearer",
    "scope": "payment_accounts"
}

2. Use your Access Token

Once you have your access_token, you can request the following types of information:

Account Numbers

Request account numbers by following these steps:

Make a GET request to the get account numbers endpoint.
In the header parameters, include the access_token retrieved from the request an access token endpoint.
The response returns a variety of account information including account_number, routing_number, and more.

1
2
3
4
5
curl -L -X GET 'https://int-api.mx.com/account/account_numbers' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Bearer PROCESSOR_TOKEN_GOES_HERE'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "account_numbers":[
  {
    "guid":"ACN-68c0b681-78c2-4731-9b41-d6e8ae2846cf",
    "user_guid":"USR-101ad774-288b-44ed-ad16-da87d522ea20",
    "member_guid":"MBR-54feffb9-8474-47bd-8442-de003910113a",
    "account_guid":"ACT-32a64160-582a-4f00-ab34-5f49cc35ed35",
    "account_number":"6366816006",
    "routing_number":"242722023",
    "transit_number":null,
    "institution_number":null,
    "loan_guarantor":null,
    "loan_reference_number":null,
    "sequence_number":null
  }
],
    "pagination":{
      "current_page":1,
      "per_page":25,
      "total_entries":1,
      "total_pages":1
    }
}

Account Owner Information

Request account owner or identity information by following these steps:

Make a GET request to the get account owner information endpoint.
In the header parameters, include your bearer access_token as shown in the request example that follows.
The response returns account owner information associated with the member.

1
2
3
curl -L -X GET 'https://int-api.mx.com/account/account_owners' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Bearer PROCESSOR_TOKEN_GOES_HERE'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "account_owners":[
  {
    "guid":"ACO-a06b74ec-6a58-4c0b-b437-8de5e03194ac",
    "user_guid":"USR-101ad774-288b-44ed-ad16-da87d522ea20",
    "member_guid":"MBR-54feffb9-8474-47bd-8442-de003910113a",
    "account_guid":"ACT-283132a4-1401-486a-909e-1605f1623d11",
    "owner_name":"Janita Pollich",
    "address":"3541 Adrian Street",
    "city":"North Kishaberg",
    "state":"Maine",
    "postal_code":"45054-7764",
    "country":null,
    "email":"janita.pollich823@beerpowlowski.ca",
    "phone":"676-932-5861"
  },
  {
    "guid":"ACO-74eb553b-2612-4b09-9b8b-a8c2dcdd4025",
    "user_guid":"USR-101ad774-288b-44ed-ad16-da87d522ea20",
    "member_guid":"MBR-54feffb9-8474-47bd-8442-de003910113a",
    "account_guid":"ACT-32a64160-582a-4f00-ab34-5f49cc35ed35",
    "owner_name":"Janita Pollich",
    "address":"3541 Adrian Street",
    "city":"North Kishaberg",
    "state":"Maine",
    "postal_code":"45054-7764",
    "country":null,
    "email":"janita.pollich823@beerpowlowski.ca",
    "phone":"676-932-5861"
  }
  ],
  "pagination":{
    "current_page":1,
    "per_page":25,
    "total_entries":7,
    "total_pages":1
  }
}

Transaction History

Request transaction history data by following these steps:

Make a GET request to get transaction history endpoint.
In the header parameters, include your bearer access_token as shown in the request example that follows.
The response returns transaction data from up to 90 days in the past. For more information on these response parameters, visit our API reference.

1
2
3
curl -L -X GET 'https://int-api.mx.com/account/transactions' \      
-H 'Accept: application/vnd.mx.api.v1+json' \                                                                                                                              
-H 'Authorization: Bearer PROCESSOR_TOKEN_GOES_HERE'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
{
  "transactions": [
      {
        "category":"Restaurants",
        "created_at":"2022-03-10T08:44:18Z",
        "date":"2022-03-09",
        "posted_at":"2022-03-09T16:46:00Z",
        "status":"POSTED",
        "top_level_category":"Food & Dining",
        "transacted_at":"2022-03-09T16:46:00Z",
        "type":"DEBIT",
        "updated_at":"2022-03-10T08:44:18Z",
        "account_guid":"ACT-abf38024-53cd-43ee-93a6-6252e7714a69",
        "account_id":"account-968af910-7706-4b7c-a815-c7b1a9618e0a",
        "amount":18.0,
        "category_guid":"CAT-006862be-64a0-e778-f035-0936445b9c16",
        "check_number_string":null,
        "currency_code":null,
        "description":"Bob's Test",
        "extended_transaction_type":"",
        "guid":"TRN-be454fa0-f3da-455c-80a0-83e54ad94fd2",
        "id":"transaction-db60fda2-3748-47e9-ba08-294658645e22",
        "is_expense":true,
        "is_fee":false,
        "is_income":false,
        "is_international":false,
        "is_recurring":null,
        "latitude":null,
        "localized_description":null,
        "localized_memo":null,
        "longitude":null,
        "member_guid":"MBR-54feffb9-8474-47bd-8442-de003910113a",
        "member_is_managed_by_user":true,
        "memo":null,
        "merchant_category_code":0,
        "merchant_guid":null,
        "merchant_location_guid":null,
        "metadata":"some hard coded transaction metadata",
        "original_description":"Bob's Test",
        "user_guid":"USR-101ad774-288b-44ed-ad16-da87d522ea20",
        "user_id":"My-Unique-ID",
        "business_category":null,
        "business_category_guid":"FCT-230b6f73-145d-42cf-b5a9-176d4fa4fd82",
        "is_business":false,
        "is_bill_pay":false,
        "is_direct_deposit":false,
        "is_overdraft_fee":false,
        "is_payroll_advance":false,
        "is_subscription":false
    }
  ],
    "pagination":{
        "current_page":1,
        "per_page":25,
        "total_entries":1,
        "total_pages":1
    }
}

Payment Account Information

Request payment account information using the following steps:

Make a GET request to the request payment account information endpoint.
In the header parameters, include the access_token retrieved from the request an access token endpoint shown in the following request example.
The response returns a variety of account information including account_number, routing_number, and the available_balance.

1
2
3
4
curl -L -X GET 'https://int-api.mx.com/payment_account' \
-H 'accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Bearer PROCESSOR_TOKEN_GOES_HERE' \

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "payment_account": {
        "account_name": "Gringotts Savings",
        "account_number": "1858091489",
        "account_type": 2,
        "available_balance": 1000.0,
        "balance": 1000.0
        "routing_number": "10654341",
        "transit_number": null,
        "updated_at":"2022-04-22T08:52:10Z",
        "created_at":"2022-03-17T20:38:57
    }
}

Real-time Account Balances

Request real-time account balances to determine whether an account has a sufficient balance to initiate and process a transfer, inform your end user about potential overdraft fees, and more.

If you require more recent account balance information than is displayed in the payment account information endpoint response, use the following process.

To request real-time account balances, use a combination of two endpoints:

A. Use the /account/check_balance endpoint to pull more recent account balance information about a member.
B. Use the /payment_account endpoint to retrieve the actual real-time balance in the response.

A. Real-Time Account Balance

After you’ve received an access_token, use the following steps to begin aggregating account balance information.

Make a POST request to the get account balance endpoint.
In the header parameters, include the access_token retrieved from the request an access token endpoint.
Similar to aggregation, the response returns several member fields that indicate whether the requested balance information has been gathered.

1
2
3
curl -L -X POST 'https://int-api.mx.com/account/check_balance'
-H 'Accept: application/vnd.mx.api.v1+json'
-H 'Authorization: Bearer PROCESSOR_TOKEN_GOES_HERE'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
class MemberResponseBody {
  Member: class MemberResponse {
    AggregatedAt: 2016-10-13T18:07:57.000Z,
    BackgroundAggregationIsDisabled: False,
    ConnectionStatus: CONNECTED,
    Guid: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b,
    Id: unique_id,
    InstitutionCode: chase,
    IsBeingAggregated: False,
    IsManagedByUser: False,
    IsOauth: False,
    Metadata: \"credentials_last_refreshed_at\": \"2015-10-15\",
    Name: Chase Bank,
    OauthWindowUri: int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp,
    SuccessfullyAggregatedAt: 2016-10-13T17:57:38.000Z,
    UserGuid: USR-fa7537f3-48aa-a683-a02a-b18940482f54,
    UserId: user123
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
mxplatformgo.MemberResponseBody{
  Member: mxplatformgo.MemberResponse{  
    AggregatedAt: "2016-10-13T18:07:57.000Z"
    BackgroundAggregationIsDisabled: false
    ConnectionStatus: "CONNECTED"
    Guid: "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b"
    Id: "unique_id"
    InstitutionCode: "chase"
    IsBeingAggregated: false
    IsManagedByUser: false
    IsOauth: false
    Metadata: "\"credentials_last_refreshed_at\": \"2015-10-15\""
    Name: "Chase Bank"
    OauthWindowUri: "int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp"
    SuccessfullyAggregatedAt: "2016-10-13T17:57:38.000Z"
    UserGuid: "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
    UserId: "user123"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
class MemberResponseBody {
  member: class MemberResponse {  
    aggregatedAt: 2016-10-13T18:07:57.000Z
    backgroundAggregationIsDisabled: false
    connectionStatus: CONNECTED
    guid: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b
    id: unique_id
    institutionCode: chase
    isBeingAggregated: false
    isManagedByUser: false
    isOauth: false
    metadata: \"credentials_last_refreshed_at\": \"2015-10-15\"
    name: Chase Bank
    oauthWindowUri: int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp
    successfullyAggregatedAt: 2016-10-13T17:57:38.000Z
    userGuid: USR-fa7537f3-48aa-a683-a02a-b18940482f54
    userId: user123
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  member: {  
    aggregated_at: '2016-10-13T18:07:57.000Z',
    background_aggregation_is_disabled: false,
    connection_status: 'CONNECTED',
    guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    id: 'unique_id',
    institution_code: 'chase',
    is_being_aggregated: false,
    is_managed_by_user: false,
    is_oauth: false,
    metadata: '\"credentials_last_refreshed_at\": \"2015-10-15\"',
    name: 'Chase Bank',
    oauth_window_uri: 'int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    successfully_aggregated_at: '2016-10-13T17:57:38.000Z',
    user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    user_id: 'user123'
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  'member': {  
    'aggregated_at': '2016-10-13T18:07:57.000Z',
    'background_aggregation_is_disabled': False,
    'connection_status': 'CONNECTED',
    'guid': 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    'id': 'unique_id',
    'institution_code': 'chase',
    'is_being_aggregated': False,
    'is_managed_by_user': False,
    'is_oauth': False,
    'metadata': '\"credentials_last_refreshed_at\": \"2015-10-15\"',
    'name': 'Chase Bank',
    'oauth_window_uri': 'int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    'successfully_aggregated_at': '2016-10-13T17:57:38.000Z',
    'user_guid': 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    'user_id': 'user123'
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
#<::MxPlatformRuby::MemberResponseBody
  @member=#<::MxPlatformRuby::MemberResponse  
    @aggregated_at='2016-10-13T18:07:57.000Z',
    @background_aggregation_is_disabled=false,
    @connection_status='CONNECTED',
    @guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    @id='unique_id',
    @institution_code='chase',
    @is_being_aggregated=false,
    @is_managed_by_user=false,
    @is_oauth=false,
    @metadata='\"credentials_last_refreshed_at\": \"2015-10-15\"',
    @name='Chase Bank',
    @oauth_window_uri='int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    @successfully_aggregated_at='2016-10-13T17:57:38.000Z',
    @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    @user_id='user123'
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "member": {  
    "aggregated_at": "2016-10-13T18:07:57.000Z",
    "background_aggregation_is_disabled": false,
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "id": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": false,
    "is_managed_by_user": false,
    "is_oauth": false,
    "metadata": "\"credentials_last_refreshed_at\": \"2015-10-15\"",
    "name": "Chase Bank",
    "oauth_window_uri": "int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp",
    "successfully_aggregated_at": "2016-10-13T17:57:38.000Z",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "user123"
  }
}

B. Request Payment Account Information

When the connection_status is CONNECTED from your previous request, you can request real-time account balance using the payment account information endpoint.

Use the following steps:

Make a GET request to the request payment account information endpoint.
In the header parameters, include the access_token retrieved from the request an access token endpoint shown in the following request example.
The response returns newly aggregated account balance and payment account information.

1
2
3
4
curl -L -X GET 'https://int-api.mx.com/payment_account' \
-H 'accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Bearer PROCESSOR_TOKEN_GOES_HERE' \

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "payment_account": {
        "account_name": "Gringotts Savings",
        "account_number": "1858091489",
        "account_type": 2,
        "available_balance": 1000.0,
        "balance": 1000.0
        "routing_number": "10654341",
        "transit_number": null,
        "updated_at":"2022-04-22T08:52:10Z",
        "created_at":"2022-03-17T20:38:57
    }
}

Next Steps

Success!

You’re all done. At this point, you can use your token to request account numbers, account owner information, or transaction history. Take a look at our API reference if you need information about our endpoints at a glance.

API Reference

Success!

Was this page helpful?