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