Skip to main content

How-to Guide for Clients

Getting Started​

This guide is intended for our clients using the MX Platform API. It explains how to move money with a processor by giving them access to user data with an authorization code. This authorization code is then sent to the 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.

Demo App​

Our demo app provides a concrete implementation of processor tokens and demonstrates how they fit into the MX ecosystem using a simple Ruby on Rails app. Install, run, and review the app's code to see understand more about how the process works. The demo app is hosted on GitHub.

Get an Authorization Code​

The workflow is as follows:

  1. Create a user (API call).
  2. Connect and verify account numbers (API call and Connect Widget UI).
  3. List verified accounts (API call).
  4. Identify account owners (optional; multiple API calls).
  5. Request the authorization code.
  6. If your processor does not require account owner information, you don’t need to complete the identity step.
Step 1

Create a User​

A user represents your end user in the MX Platform. Make a request to the Create User endpoint (POST /users).

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.

info

None of these parameters are required, but the user object can't be empty. We recommend that you always set the id parameter when creating a user.

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.

Request
Response
Language:shell

_12
curl -i -X POST 'https://int-api.mx.com/users' \
_12
-u 'client_id:api_key' \
_12
-H 'Accept: application/vnd.mx.api.v1+json' \
_12
-H 'Content-Type: application/json' \
_12
-d '{
_12
"user": {
_12
"id": "partner-2345",
_12
"is_disabled": false,
_12
"email": "example@example.com",
_12
"metadata": "Some metadata"
_12
}
_12
}'

Step 2

Connect and Verify Account Numbers​

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. Use the Connect Widget 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.

Some processors require transaction data and some do not. Configuration of the Connect Widget depends on what data the processor requires.

A. No Transaction Data Required​

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

_10
curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
_10
-H 'Accept: application/vnd.mx.api.v1+json' \
_10
-u 'client_id:api_key' \
_10
-H 'Content-type: application/json' \
_10
-d '{
_10
"widget_url": {
_10
"widget_type": "connect_widget",
_10
"mode": "verification"
_10
}
_10
}'

B. Transaction Data is Required​

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

For One-Time Transaction Data

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

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

For continuous transaction data (aggregated daily):

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

_12
curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
_12
-H 'Accept: application/vnd.mx.api.v1+json' \
_12
-u 'client_id:api_key' \
_12
-H 'Content-type: application/json' \
_12
-d '{
_12
"widget_url": {
_12
"widget_type": "connect_widget",
_12
"mode": "verification",
_12
"include_transactions": true,
_12
"disable_background_agg": false
_12
}
_12
}'

Step 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.

Request
Response
Language:shell

_10
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/account_numbers' \
_10
-H 'Accept: application/vnd.mx.api.v1+json' \
_10
-u 'client_id:api_key'

Step 4

Identify Account Owners (Optional)​

If a processor needs account owner information, complete the identification process before you request an authorization code. This enables 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 Account Owner Identification guide.

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.

Request
Response
Language:shell

_10
curl -i -X POST 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/identify' \
_10
-H 'Accept: application/vnd.mx.api.v1+json' \
_10
-H 'Content-Type: application/json' \
_10
-u 'client_id:api_key'

Step 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.

info

Authorization codes are one-time use.

Request
Response
Language:shell

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

Next Steps​

You’ve completed your part of the process. Send the authorization code to your payment processor. They’ll need to review the steps in the How-to Guide for Processors.

On this page