Quickstart

Are you a Client looking to learn more about how our Processor Token API combines our API endpoints and MXconnect widget to provide a seamless experience for generating tokens for processors? Click the Quickstart Repository button to visit our Github for a quick introduction to building with Processor Token.
Our Quickstart repository provides instructions to setting up the Quickstart.


Getting Started

This guide is intended for our Clients using the MX Platform API. It explains how to start the token request process by aggregating users, verifying and identifying members, and requesting an authorization code. You must retrieve an authorization code and provide it to your Processor before they can request an access token.

Before you can begin, we must permit the MX Platform API, account verification, and payment processing.

Ensure you have your api_key and client_id from the Client Dashboard before you begin.

Aggregate and Verify with the Connect widget

To enable processors to exchange a processor token for account payment information, account owner information (identity), and transaction history, the following jobs must be completed in this order:

  1. Aggregation (Optional)
  2. Verification (Required)
  3. Identity (Optional)

Note: If you do not require aggregation, you do not have to complete the aggregation process. Also, if your processor does not require account owner information, you don’t need to complete the identity job.

To request an authorization code, retrieve the user_guid, member_guid, and account_guid. Use the MXconnect widget, along with the following steps, to retrieve these parameters.


1. Create a User

Make a POST request to the create user endpoint, as shown below.

It’s a good idea to send along a unique id of your choice with your request. The API will also give each new user an MX-defined guid (or user_guid when appearing outside the user object). Between your id and the guid, you’ll easily be able to map between your system and ours.

You’ll need the user guid for nearly every request on the MX API, at least when using basic authorization.

You may also include metadata, such as the date the user was created, the end user’s name, etc. Just make sure not to include any sensitive information here, like credentials.

Parameters

Field Required?
email No
id No
is_disabled No
metadata No
1
2
3
4
5
6
7
8
9
10
11
12
curl -i -X POST 'https://int-api.mx.com/users' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "user": {
        "id": "partner-2345",
        "is_disabled": false,
        "email": "totally.fake.email@notreal.com",
        "metadata": "Yada yada yada"
      }
    }'
1
2
3
4
5
6
7
8
9
{
  "user": {
    "email": "totally.fake.email@notreal.com",
    "guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "id": "partner-2345",
    "is_disabled": false,
    "metadata": "Yada yada yada"
  }
}

2. Connect the User to an Institution

Connect the user to an institution using the MXconnect widget by completing either aggregation and verification, or just verification. If your use case requires you to use aggregation, request the widget url in aggregation mode as shown below. This is an optional step. If you don’t need aggregation, you can run the widget in verification mode only. If you run aggregation first, you must still run the widget in verification mode to generate an authorization code. For more information on MXconnect, review the guide.

A. Aggregate accounts using MXconnect (Optional)

If your use case requires aggregation, run the MXconnect widget in aggregation mode first. If you don’t need aggregation, start with step B to verify.

  1. Make a POST request to the widget_urls endpoint using the user_guid. Note: Ensure that the mode is [set to aggregation which is the default mode.
  2. Capture the URL for an embeddable version of MXconnect from the response.
  3. Use the URL to access MXconnect.

Example request and response

1
2
3
4
5
6
7
8
9
10
curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "widget_url": {
          "widget_type": "connect_widget",
          "mode": "verification"
        }
      }'
1
2
3
4
5
6
7
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

B. Verify the member using MXconnect

  1. Make a POST request to the widget_urls endpoint using the user_guid
    Note: Ensure that the mode is set to verification.  
  2. Capture the URL for an embeddable version of MXconnect from the response.
  3. Use the URL to access MXconnect.

Example request and response

1
2
3
4
5
6
7
8
9
10
curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "widget_url": {
          "widget_type": "connect_widget",
          "mode": "verification"
        }
      }'
1
2
3
4
5
6
7
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

3. Retrieve a List of Verified Accounts

After you verify a user, make a request to the list accounts numbers by member endpoint to capture the member_guid and the account_guid.

You’ll need both guids and the user_guid to request an authorization code.

1
2
3
curl -i 'https://int-api.mx.com/users/USR-3a17a2b1-acbc-48d1-8098-1b8ae8939ab2/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/account_numbers' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "account_numbers": [
    {
      "account_guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
      "account_number": "10001",
      "institution_number": null,
      "member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
      "routing_number": "68899990000000",
      "transit_number": null,
      "user_guid": "USR-3a17a2b1-acbc-48d1-8098-1b8ae8939ab2"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

4. Account Owner Information (Optional)

If a processor wants to request account owner information, use the identify member endpoint before you request an authorization code. Making this request before requesting an authorization code will enable processors to request account owner information using their token. It is important that you run this request only after you’ve completed aggregation and verification. Do not complete the identity member request before these steps. For more information on identity or account owner information, visit our reference here.

Make a POST request to the identify member endpoint. Use the user_guid and member_guid you retrieved in the request.

Similar to aggregation, the identify member endpoint returns a CONNECTED status if successful. If successful, the user_guid and member_guid can now be used to request an authorization code that processors can exchange to generate a token to be used for account owner information.

Example request and response

1
2
3
4
curl -i -X POST 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/identify' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -u 'client_id:api_key'
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"
  }
}

5. Transaction History (Optional)

If your processor wants to request transaction history, you must include transaction history when you configure MXconnect when connecting a user to an institution in Step 2.
Transaction data can be requested for up to 90 days in the past.

Note: If your processor is unable to request transaction data, ensure that include_transactions isn’t set to false when running aggregation using the MXconnect widget.

Configuring the MXconnect Widget for Transactions

During Step 2, you must configure several flags for the MXconnect widget. The value depends on whether the processor requires data from a one-time transaction or multiple transactions from every day. The include_transaction flag determines whether the MXconnect widget will aggregate transaction data during the request or not. The disable_background_agg flag determines whether aggregation occurs only one time (at the time of the request) or occurs continuously over the course of the connection.

For a one-time transaction:

  • Set include_transactions to true.
  • Set disable_background_agg to false.

In the example request below, we make a POST request to the request a connect URL endpoint.

Example request

1
2
3
4
5
6
7
8
9
10
11
12
curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "widget_url": {
          "widget_type": "connect_widget",
          "mode": "verification",
          "include_transactions": true,
          "disable_background_agg": true
        }
      }'

For transactions data from every day:

  • Set include transactions to true.
  • Set disable_background_agg to false.

Example request

1
2
3
4
5
6
7
8
9
10
11
12
curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "widget_url": {
          "widget_type": "connect_widget",
          "mode": "verification",
          "include_transactions": true,
          "disable_background_agg": true
        }
      }'

6. Authorization Code Request

After you’ve completed the steps to creating a user and member and retrieving a list of verified accounts, you’re ready to request an authorization code.

Use the following steps:

  1. Make a POST request to the /payment_processor_authorization_code endpoint. You must include the user_guid, member_guid, and account_guid in the body of the request.
  2. You’ll receive an authorization_code in the response.
  3. You must provide this code to the processor in order for them to request an access token.

Example request and response

1
2
3
4
5
6
7
8
9
10
11
curl -i -X POST 'http://int-api.mx.com/payment_processor_authorization_code' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -u 'client_id:api_key` 
  -d '{ "authorization_code":
    {
      "user_guid": "USR-f12b1f5a-7cbe-467c-aa30-0a10d0b2f549",
      "member_guid": "MBR-46637bc5-942d-4229-9370-ddd858bf805e",
      "account_guid": "ACT-4d4c0068-33bc-4d06-bbd6-cd270fd0135c"
    }
  }'
1
2
3
4
5
{
    "payment_processor_authorization_code": {
        "authorization_code": "AUTHORIZATION_CODE_IS_HERE"
    }
}