Demo App

Our demo app provides a concrete implementation of processor tokens, demonstrating how they fit into the MX ecosystem using a simple Ruby on Rails app. Client developers seeking to understand the process can install it, run it, and review the code to see how to implement these features using best practices. The demo app is hosted on GitHub.

Demo App

Getting Started

This guide is intended for our clients using the MX Platform API. It explains how to facilitate processor access to user data by creating a user, verifying account numbers, and requesting an authorization code. This authorization code is then sent to your processor and used by them to request an access token.

Before you can begin, MX must enable the Platform API as well as the account verification and payment processing features. You must also ensure you have your api_key and client_id from the client dashboard.

Workflow

The workflow is as follows:

Create a user (API call).
Connect and verify account numbers (API call and Connect Widget UI).
List verified accounts (API call).
Identify account owners (optional; multiple API calls).
Request an authorization code.

If your processor does not require account owner information, you don’t need to complete the identity step.

1. Create a User

The first step is to create a user. A user represents your end user in the MX Platform. Make a POST request to the create user endpoint, as shown below.

We recommend that you include a unique id of your choice with the request. You may also include metadata, such as the date the user was created or the end user’s name. Don’t include any sensitive information here, such as credentials.

In the response, the API gives each new user an MX-defined guid (or user_guid when appearing outside the user object). Between your id and the guid, you can 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.

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 and Verify Account Numbers

You connect a user to a financial institution through a member. Verifying account numbers always happens through a member, and this verification is required in order to request an authorization code. The best way to do this is through the Connect Widget, which makes it simple to create a member and verify it with an MX-provided user interface. You’ll need this member’s unique GUID for later steps as well.

For more information on the Connect Widget, review the guide.

How you configure the Connect Widget depends on what data the processor will need access to.

2.A. No Transaction Data Required

Make a POST request to the get widget URL endpoint with the user_guid from step one.
- Set the mode to verification.
- Set the widget_type to connect_widget.
Capture the URL from the response.
Load the Connect Widget URL. The end user will select an institution and proceed through the Connect Widget flow.
Capture the member_guid returned in the member connected postMessage during this flow. It will be used in the next step.

Request a Connect URL in Verification Mode Without Transaction Data

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

2.B. Transaction Data Is Required

If you or your processor’s use case requires account and transaction data in addition to account numbers, you can use the optional include_transactions parameter, which aggregates the last 90 days of transactions at the same time as verifying account numbers. You’ll also need to know whether the use case requires transaction data only once or continuously. This is determined with the disable_background_agg parameter.

2.B.A. For One-Time Transaction Data:

Make a POST request to the get widget URL endpoint with the user_guid from step one.
- Set the mode to verification.
- Set the widget_type to connect_widget
- Set include_transactions to true.
- Set disable_background_agg to true.
Capture the URL for an embeddable version of the Connect Widget from the response.
Load the Connect Widget URL. The end user will select an institution and proceed through the Connect Widget flow.
Capture the member_guid returned in the member connected postMessage during this flow. It will be used in the next step.

Request a Connect URL in Verification Mode With One-time Transaction Data

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
        }
      }'

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

2.B.B. For continuous transaction data (aggregated daily):

Make a POST request to the get widget URL endpoint with the user_guid from step one.
- Set the mode to verification.
- Set the widget_type to connect_widget
- Set include_transactions to true.
- Set disable_background_agg to false.
Capture the URL for an embeddable version of the Connect Widget from the response.
Load the Connect Widget URL. The end user will select an institution and proceed through the Connect Widget flow.
Capture the member_guid returned in the member connected postMessage during this flow. It will be used in the next step.

Request a Connect URL in Verification Mode With Continuous Transaction Data

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": false
        }
      }'

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 create and verify a member with the Connect Widget, make a request to the list accounts numbers by member endpoint to retrieve the account numbers tied to that member.

This request requires the member_guid delivered with the Connect Widget’s member connected postMessage in the previous step.

Capture the account_guid returned in this response to use later.

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/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
20
{
  "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",
      "passed_validation": true,
      "transit_number": null,
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

4. (Optional) Identify Account Owners

If a processor needs account owner information, you must complete the identification process before you request an authorization code. This will enable processors to request account owner information using their token.

It is important that you complete this process only after you’ve completed the steps outlined above. For more information on identity or account owner information, visit our identity reference.

Identifying account owner information is itself a multi-step process which can potentially involve multi-factor authentication, and can’t be completed with the Connect Widget. You must begin it by making a POST request to the identify member endpoint with the user_guid and member_guid you captured in previous steps, which is shown in the example below.

For a more complete guide on the identification process, see our aggregation guide, as aggregation and identification are extremely similar.

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": "https://mxbank.mx.com/oauth/authorize?client_id=b8OikQ4Ep3NuSUrQ13DdvFuwpNx-qqoAsJDVAQCyLkQ&redirect_uri=https%3A%2F%2Fint-app.moneydesktop.com%2Foauth%2Fredirect_from&response_type=code&scope=openid&state=d745bd4ee6f0f9c184757f574bcc2df2",
    "successfully_aggregated_at": "2016-10-13T17:57:38.000Z",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "user123"
  }
}

5. Request an Authorization Code

You’re now ready to request an authorization code with the following steps:

Make a POST request to the /authorization_code endpoint. In the body of the request, you must include the user_guid, member_guid, and account_guid captured in previous steps. You’ll receive an authorization code in the response.

1
2
3
4
5
6
7
8
9
curl -i -X POST 'https://int-api.mx.com/authorization_code' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-u 'client_id:api_key' \
-d '{
      "authorization_code": {
        "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"
      }
    }'

1
2
3
4
5
{
  "authorization_code": {
    "code": "9nN-9D8_4Z3WYazx7-zXfmqsD3jwgL_2W927Sb3otI"
  }
}

Demo App

Getting Started

Workflow

1. Create a User

2. Connect and Verify Account Numbers

2.A. No Transaction Data Required

Request a Connect URL in Verification Mode Without Transaction Data

2.B. Transaction Data Is Required

Request a Connect URL in Verification Mode With One-time Transaction Data

Request a Connect URL in Verification Mode With Continuous Transaction Data

3. Retrieve a List of Verified Accounts

4. (Optional) Identify Account Owners

5. Request an Authorization Code

Was this page helpful?