Skip to main content

Fetch Account and Routing Numbers with Connect

Legacy Guide

This guide is for Platform API v2011101. For guidance on the newest version, see Connectivity Integration Guides.

MX's Instant Account Verification (IAV) feature allows partners to access account and routing numbers. When used in combination with Account Owner Identification and Balance Checks, account numbers can be used for a number of purposes, such as money movement through the ACH system or account origination.

Before following the steps in this guide, you'll need to:

Keep the following in mind:

  • IAV applies only to demand deposit accounts. Functionally, this means that only CHECKING and SAVINGS accounts are likely to return account/routing numbers.
  • IAV does not provide a complete money movement or payments solution. Rather, it provides the necessary account numbers to facilitate payments through payment processors and the ACH system.
  • Account and routing numbers can be used for ACH transfers for as long as the account is still open, and there is generally no need to run more than one IAV for the account.

Workflow​

You'll use this workflow with the Connect Widget.

  1. Create a user.
  2. Load the Connect Widget in verification mode for that user. The end user will use the Connect Widget to create a member, start aggregating IAV data, and answer multi-factor authentication if necessary.
  3. The end user interacts with the Connect Widget.
    • Listen for and handle event messages; the Connect Widget will deliver the member connected event message if successful.
    • Polling the member status helps deal with cases where the Connect Widget is closed early or unexpectedly; a verification is successful when the member connection_status is CONNECTED and the is_aggregating field changes from true to false.
  4. Read the account numbers.
  5. Read the account's details to confirm it is open and has sufficient funds.
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

Request a Connect Widget URL​

Please see our API Reference for complete information on the behaviors and settings affected by verification mode.

Make a POST request to the /users/{user_guid}/widget_urls endpoint

  • Set the mode parameter to verification.
  • Set the widget_type parameter to connect_widget.

If your use case requires access to account owner information like name and address, you can use the include_identity parameter, as described in Request Widget URL. This will tell the Connect Widget to aggregate account owner aggregation after IAV data has finished aggregating.

Setting the mode to verification limits Connect Widget search results to institutions that support IAV. Setting include_identity further limits search results to institutions that support both IAV and account owner aggregation.

info

Widget URLs are one-time use. You must fetch a new widget URL each time you load the widget.

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

Step 3

Load the URL and Let the End User Interact​

info

If you're following this guide for testing purposes, you must search for the test institution in the widget and enter the credentials mentioned in one of our testing guides.

Load the URL in your application or website. At this point the end user will interact with the Connect Widget. The widget handles the creation of a member as well as the IAV process and any MFA that may be encountered. It automatically asks end users to search for an institution, give their credentials, or authenticate with OAuth. It also deals with any errors along the way.

You'll need to listen for a couple important event messages from the Connect Widget:

  • member status updated which gives you the member GUID and the current connection_status.
  • member connected tells you that the member has been successfully connected and you can move on to the next steps.

Alternatively, if the end user closes the Connect Widget early or some other problem occurs before you see a CONNECTED status, you can use the member_guid to immediately check the member's connection status with a dedicated API endpoint.

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/status' \
_10
-H 'Accept: application/vnd.mx.api.v1+json' \
_10
-u 'client_id:api_key'

Step 4

List the Account Numbers​

The aggregation of IAV data is now complete and you can list account and routing numbers.

Make a GET request to /users/{user_guid}/members/{member_guid}/account_numbers.

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'

info
  • If MX has both an account number and a routing number for at least one of the member's accounts, that information will be returned. No information will be returned for accounts that are missing a value for one or both of these fields.
  • The account number returned from this endpoint may be a Tokenized Account Number (TAN). See the section on TANs for information on dealing with these properly.
  • There is another endpoint for listing account numbers provided for code convenience: GET /users/{user_guid}/members/{member_guid}/accounts/{account_guid}/account_numbers
Step 5

List Account Data​

Before using the account numbers you've just gathered for things like ACH transfers, you'll need to read the account's details to confirm that:

  • The available_balance shows sufficient funds.
  • The account is still open: is_closed: false.

The process was successful and you can now read account information.

Make a GET request to the /users/{user_guid}/members/{member_guid}/accounts endpoint. The response will include all the accounts belonging to the member.

Request
Response
Language:shell

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

info

There is another endpoint for listing accounts which may be more suitable for your use case: GET /users/{user_guid}/accounts.

You may also consider reading the attributes of a specific account. There are two endpoints for this which return the same information, provided for code convenience:

GET /users/{user_guid}/members/{member_guid}/accounts/{account_guid}

GET /users/{user_guid}/accounts/{account_guid}

Step 6

Work With a Payment Processor to Move Money​

Now that you have valid account/routing numbers and have confirmed there is sufficient balance in the account, you can work with a payment processor to move money on the ACH system.

On this page