> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# How-to Guide for Processors
## 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 need your `api_key` and `processor_id`, which can be found on the [Client Dashboard](https://dashboard.mx.com).
## 1. Request an Access Token
**INFO**
The authorization code used in this request is one-time use.
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. Every `access_token` expires after 60 days. To get a new token after an old one has expired, you must get a new code from the client.
1. Make a `POST` request to the /token endpoint.
2. In the query string parameters, include the code as shown in example.
3. In the authorization header, include your `processor_id` and `api_key`. See the reference section on authentication for more information on this header.
```shell Request theme={null}
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'
```
```json Response theme={null}
{
"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"
}
```
## 2. Use your Access Token
Once you have your `access_token`, you can request the following types of information:
* [Real-time account balance](/products/connectivity/instant-account-verification/processor-token/processor-guide#real-time-account-balances) (This should be the first request you make; it helps prevent failures due to insufficient funds, closed accounts, etc.).
* [Account numbers](/products/connectivity/instant-account-verification/processor-token/processor-guide#account-and-routing-numbers)
* [Account owner information](/products/connectivity/instant-account-verification/processor-token/processor-guide#account-owner-information)
* [Transaction history](/products/connectivity/instant-account-verification/processor-token/processor-guide#transaction-history)
* [Payment account information](/products/connectivity/instant-account-verification/processor-token/)
### Real-time Account Balances
First, use your access token to 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 helps 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 fetch the latest balance information.
2. Use the `/payment_account` endpoint to read the fetched balance information.
#### 1. Check Real-Time Account Balance
Checking a balance 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. For more information on checking balances, review our Balance Checks guide.
**INFO**
This endpoint only aggregates balance-related data; it does not include transactional data. Neither does it return balance data in the response. You'll read balance data in the next step.
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.
* Gathering balance data may take time, so check on the status of the connection. Initially, you should see the `is_being_aggregated` field return with `true`.
```shell Request theme={null}
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'
```
```json Response theme={null}
{
"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 connection 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.
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.
```shell Request theme={null}
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'
```
```json Response theme={null}
{
"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"
}
}
```
#### 2. Read Balance Information
Read the aggregated balance data as follows. The response includes the account's balance and other information about the payment account.
1. Make a `GET` request to the `/payment_account` endpoint.
2. In the `Authorization` header, set the type to `Bearer` and include the `access_token` retrieved at the beginning of this guide.
```shell Request theme={null}
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'
```
```json Response theme={null}
{
"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.
2. In the `Authorization` header, set the type to `Bearer` and include the `access_token` retrieved in step 1.
```shell Request theme={null}
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'
```
```json Response theme={null}
{
"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.
2. In the `Authorization` header, set the type to `Bearer` and include the `access_token` retrieved in Step 1.
```shell Request theme={null}
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'
```
```json Response theme={null}
{
"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.
2. In the `Authorization` header, set the type to `Bearer` and include the `access_token` retrieved in step 1.
```shell Request theme={null}
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'
```
```json Response theme={null}
{
"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 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.
2. In the `Authorization` header, set the type to `Bearer` and include the `access_token` retrieved at the beginning of this guide.
```shell Request theme={null}
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'
```
```json Response theme={null}
{
"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
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.