MX Integration

Suggest Edits

Getting started

Integrators will utilize Fortress's APIs to generate a widget url, that will allow a loaded secure iframe on their front end for an end-user to select their bank to connect. See the schema HERE

Once you have the url, you'll want to initialize your front end iframe using the following script:

<script src="https://atrium.mx.com/connect.js"></script>
    <script>
      var mxConnect = new window.MXConnect({
        id: "connect-widget", //id of where the widget will load into
        iframeTitle: "Connect",
        /**
         * Callback that for handling all events within Connect.
         * Only called in  ui_message_version 4 or higher.
         *
         * The events called here are the same events that come through post
         * messages.
         */
        onEvent: function(type, payload) {
          console.log("onEvent", type, payload);
        },
        config: {
          mode: "verification",
          color_scheme: "dark", //or "light"
          ui_message_version: 4
        },
        targetOrigin: "*"
      })
       mxConnect.load(*WIDGET URL GOES HERE*)
    </script>

Note: for sandbox testing, you can use the login credentials:
Select one of the MX Banks
Username: mxuser
Password: Any

To your end-user, the flow will look something like this:

676

After they've selected their bank:

612

On finishing the bank connection:

1020

After a successful bank linking, you'll have an event fired that looks like this:

512

Save the member_guid for the next steps.

Now use this call to connect the member_guid to the identityId of the end user.

POST /api/trust/v1/financial-institutions/members

{
  "identityId": "d540f25e-5d97-4ba9-9e64-f50a3716f59c", //Identity object pertaining to the end user
  "memberGuid": "MBR-ab11f6eb-96bd-4720-b4b2-bdf042cb0187" //member_guid returned from successful bank linking in above step
}

Retrieve any bank accounts that are connected 

GET /api/trust/v1/financial-institutions/accounts/{identityId}/{memberGuid}

//Sample Response

[
  {
    "name": "Checking",
    "accountNumberLast4": "x3544",
    "accountGuid": "ACT-92f8ecd9-2d9b-4dfe-bd1e-4426f0c7j8h2" //used to establish an externalAccount in the Fortress APIs
  }
]

📘

Multiple Accounts

If multiple accounts appear in the above call, give your end user the ability to select which one they would like to connect.

Now that you have the accountGuid, you will follow up with one last call to create a persistent object referencing the linked bank.

POST /api/trust/v1/external-accounts/financial

//Sample Request

{
  "identityId": "d540f25e-5d97-4ba9-9e64-f50a3716f59c", //identityId of the end user
  "financialAccountId": "ACT-92f8ecd9-2d9b-4dfe-bd1e-4426f0c7j8h2" //accountGuid from the above step
}

This externalAccount object created can now be used to reference the linked bank account for any ACH deposit/withdrawals in the system. The next section will go over making those kinds of payments using the externalAccount.

Updated 5 months ago