MX Integration

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

Note: The MX widget does not currently work in our sandbox environment which we are working on rectifying. To test the ACH flow, please visit Testing ACH in Sandbox

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>
    

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

After they've selected their bank:

On finishing the bank connection:

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

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

Query Params: identityId //identityId of the end user "d540f25e-5d97-4ba9-9e64-f50a3716f59c"

//Sample Response

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

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.