Getting Started

This guide explains how to request an access token as well as 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. As a processor, you can request the following types of information:

Payment Account Information
Account Numbers
Account Owner Information
Transaction History
Account Balance

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.

Access Token Request

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.

Example request and response

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"
}

Payment Account Information Request

After you’ve received an access_token, request payment account information using the following:

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.

Example request and response

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
    }
}

Account Numbers Request

After you’ve received an access_token, request member 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.

Example request and response

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

After you’ve received an access_token, request account owner information using the following:

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.

Example request and response

1
2
3
curl -L -X GET 'http://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

After you’ve received an access_token, retrieve transaction history by making 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.

Example request and response

1
2
3
curl -L -X GET 'http://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
    }
}

Account Balance Request

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 so on.

After you’ve received an access_token, request a real-time account balance by following these steps:

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.

Example request and response

1
2
3
curl -L -X POST 'http://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
class MemberResponseBody {
  Member: class MemberResponse {
    AggregatedAt: 2016-10-13T18:07:57.000Z,
    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
mxplatformgo.MemberResponseBody{
  Member: mxplatformgo.MemberResponse{  
    AggregatedAt: "2016-10-13T18:07:57.000Z"
    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
class MemberResponseBody {
  member: class MemberResponse {  
    aggregatedAt: 2016-10-13T18:07:57.000Z
    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
{
  member: {  
    aggregated_at: '2016-10-13T18:07:57.000Z',
    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
{
  'member': {  
    'aggregated_at': '2016-10-13T18:07:57.000Z',
    '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
#<::MxPlatformRuby::MemberResponseBody
  @member=#<::MxPlatformRuby::MemberResponse  
    @aggregated_at='2016-10-13T18:07:57.000Z',
    @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
{
  "member": {  
    "aggregated_at": "2016-10-13T18:07:57.000Z",
    "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"
  }
}

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

Getting Started

Access Token Request

Example request and response

Payment Account Information Request

Example request and response

Account Numbers Request

Example request and response

Account Owner Information Request

Example request and response

Transaction History Request

Example request and response

Account Balance Request

Example request and response

Success!

Was this page helpful?