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. In addition to this code, you will also need your api_key and processor_id, which can be found on the Client Dashboard.

1. Request an Access Token

After you have received a code, request an access_token as follows. The response returns an access_token which you’ll use in later steps to actually request user data.

  1. Make a POST request to the /token endpoint.
    • In the query string parameters, include the code as shown in example.
    • In the authorization header, include your processor_id and api_key. See the reference section on authentication for more information on this header.
1
2
3

curl -i -L -X POST 'https://int-api.mx.com/token?grant_type=authorization_code&code=9nN-9D8_4Z3WYazx7-zXfmqsD3jwgL_2W927Sb3otI' \
-H 'accept: application/vnd.mx.api.v1+json' \
-u 'payment_processor_id:api_key' \

1
2
3
4
5
6

{
  "access_token": "DCOwM2Zxxc0YO507ZZqIiJ8gBN5HdSQG4_g3v3xjFlGUM",
  "expires_at": null,
  "scope": "user-guid:USR-101ad774-288b-44ed-ad16-da87d522ea20 member-guid:MBR-54feffb9-8474-47bd-8442-de003910113a account-guid:ACT-32a64160-582a-4f00-ab34-5f49cc35ed35 read-protected",
  "token_type": "Bearer"
}

Every access_token expires after 60 days. To get a new token after an old one has expired, you’ll need to first get a new code from the client.

2. Use your Access Token

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

Real-time Account Balances

For many use cases, the first thing you should do with your access token is get the real-time balance for the account. This involves a request to gather (aggregate) the information, followed by a request to read the information.

Checking balances before processing a payment or submitting a transaction to a system like ACH can help prevent errors resulting from insufficient funds or closed accounts. It also allows you to inform end users about potential overdraft fees and other potential issues.

  1. Use the /account/check_balance endpoint to aggregate the latest balance information.
  2. Use the /payment_account endpoint to read the aggregated balance information.

1. Check Real-Time Account Balance

Checking a balance is similar to aggregation, and the response returns a member object. This member describes the state of the connection between the user and their financial institution and indicates whether the requested balance information has been successfully gathered.

  1. Make a POST request to the /account/check_balance endpoint.
    • In the Authorization header, set the type to Bearer and include the access_token retrieved at the beginning of this guide.
    • This first call should return with a status of 200 OK and include a member object in the body.
    • Aggregating balance data takes some time, and you will need to check on the status of the balance job. Initially, you should see the is_being_aggregated field return with true.
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

{
  "member": {
    "aggregated_at": "2022-11-30T17:25:27Z",
    "background_aggregation_is_disabled": false,
    "connection_status": "CONNECTED",
    "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "is_managed_by_user": true,
    "is_oauth": false,
    "metadata": "Additional information",
    "name": "MX Bank",
    "successfully_aggregated_at": "2022-11-30T09:36:10Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": "U-201709221210"
  }
}

  1. Check the status of the balance job by calling the /account/check_balance endpoint again.

    • These subsequent calls should return with a status of 202 Accepted rather than 200 OK, and they will include the current state of the member.
    • Keep in mind, however, that you can only call this endpoint 5 times every 2 hours for a given member.

  2. Move on to the next step when the following state is reached:

    • connection_status: CONNECTED
    • is_being_aggregated: false
    • successfully_aggregated_at updates to the current time.
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

{
  "member": {
    "aggregated_at": "2022-11-30T09:36:25Z",
    "background_aggregation_is_disabled": false,
    "connection_status": "CONNECTED",
    "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": false,
    "is_managed_by_user": true,
    "is_oauth": false,
    "metadata": "Additional information",
    "name": "MX Bank",
    "successfully_aggregated_at": "2022-11-30T09:36:25Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": "U-201709221210"
  }
}

2. Read Balance Information

Read the aggregated balance data as follows. The response will include the account’s balance and other information about the payment account.

  1. Make a GET request to the /payment_account endpoint.
    • In the Authorization header, set the type to Bearer and include the access_token retrieved at the beginning of this guide.
1
2
3

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
14
15
16

{
  "payment_account": {
    "account_guid": "ACT-32a64160-582a-4f00-ab34-5f49cc35ed35",
    "account_name": "MX Bank Checking",
    "account_number": "6366816006",
    "account_type": "CHECKING",
    "available_balance": 1000,
    "balance": 1000,
    "created_at": "2022-03-17T20:38:58Z",
    "member_guid": "MBR-54feffb9-8474-47bd-8442-de003910113a",
    "routing_number": "242722023",
    "transit_number": null,
    "updated_at": "2022-11-29T08:02:07Z",
    "user_guid": "USR-101ad774-288b-44ed-ad16-da87d522ea20"
  }
}

Account and Routing Numbers

Request account numbers as follows. The response includes information like account_number, routing_number, and more.

  1. Make a GET request to the /account/account_numbers endpoint.
    • In the Authorization header, set the type to Bearer and include the access_token retrieved in step 1.
1
2
3

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
24

{
  "account_numbers": [
    {
      "account_guid": "ACT-32a64160-582a-4f00-ab34-5f49cc35ed35",
      "account_number": "6366816006",
      "guid": "ACN-68c0b681-78c2-4731-9b41-d6e8ae2846cf",
      "institution_number": null,
      "loan_guarantor": null,
      "loan_reference_number": null,
      "member_guid": "MBR-54feffb9-8474-47bd-8442-de003910113a",
      "passed_validation": true,
      "routing_number": "242722023",
      "sequence_number": null,
      "transit_number": null,
      "user_guid": "USR-101ad774-288b-44ed-ad16-da87d522ea20"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

Account Owner Information

Request account owner or identity information as follows. The response includes information like the name and address of the account’s owner.

  1. Make a GET request to the /account/account_owners endpoint endpoint.
    • In the Authorization header, set the type to Bearer and include the access_token retrieved in step 1.
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 data as follows. The response returns up to 90 days of transaction history. For more information on response fields, see the transaction reference.

  1. Make a GET request to the /account/transactions endpoint endpoint.
    • In the Authorization header, set the type to Bearer and include the access_token retrieved in step 1.
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

Read the aggregated balance data as follows. The response will include the account’s balance and other information about the payment account.

  1. Make a GET request to the /payment_account endpoint.
    • In the Authorization header, set the type to Bearer and include the access_token retrieved at the beginning of this guide.
1
2
3

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
14
15
16

{
  "payment_account": {
    "account_guid": "ACT-32a64160-582a-4f00-ab34-5f49cc35ed35",
    "account_name": "MX Bank Checking",
    "account_number": "6366816006",
    "account_type": "CHECKING",
    "available_balance": 1000,
    "balance": 1000,
    "created_at": "2022-03-17T20:38:58Z",
    "member_guid": "MBR-54feffb9-8474-47bd-8442-de003910113a",
    "routing_number": "242722023",
    "transit_number": null,
    "updated_at": "2022-11-29T08:02:07Z",
    "user_guid": "USR-101ad774-288b-44ed-ad16-da87d522ea20"
  }
}

Next Steps

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