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.
- 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
andapi_key
. See the reference section on authentication for more information on this header.
- In the query string parameters, include the
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 balance (This should often be the first request you make, as it helps prevent failures due to insufficient funds, closed accounts, etc.).
- Account numbers
- Account owner information
- Transaction history
- Payment account 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.
- Use the /account/check_balance endpoint to aggregate the latest balance information.
- 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.
- Make a POST request to the
/account/check_balance
endpoint.- In the
Authorization
header, set the type toBearer
and include theaccess_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 withtrue
.
- In the
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"
}
}
-
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 than200 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.
- These subsequent calls should return with a status of
-
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.
- Make a GET request to the
/payment_account
endpoint.- In the
Authorization
header, set the type toBearer
and include theaccess_token
retrieved at the beginning of this guide.
- In the
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.
- Make a
GET
request to the/account/account_numbers
endpoint.- In the
Authorization
header, set the type toBearer
and include theaccess_token
retrieved in step 1.
- In the
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.
- Make a GET request to the
/account/account_owners
endpoint endpoint.- In the
Authorization
header, set the type toBearer
and include theaccess_token
retrieved in step 1.
- In the
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.
- Make a GET request to the
/account/transactions
endpoint endpoint.- In the
Authorization
header, set the type toBearer
and include theaccess_token
retrieved in step 1.
- In the
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.
- Make a GET request to the
/payment_account
endpoint.- In the
Authorization
header, set the type toBearer
and include theaccess_token
retrieved at the beginning of this guide.
- In the
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"
}
}