Linked Counterparties

Fiat US Linked

Linked counterparties (e.g. FIAT_US_LINKED) allow end users to link their US domiciled external accounts using MX. Linked counterpartes can then be used to pull funds (via ACH) from or push funds (via ACH) into these external accounts. A single Fiat US Linked counterparty can only support ACH at this time.

To create a Fiat US Linked counterparty, you have to follow the following steps

1. Create the Counterparty of type FIAT_US_LINKED using the use the counterparties endpoint .
2. Retrieve the MX Widget URL for this newly created Counterparty, using the counterparties/{COUNTERPARTY_ID}/link/details endpoint
3. Pass in the MX Widget URL to the MX Widget script below. You will have to put this script into an iframe in your UI. For testing purposes in sandbox, you can also use our utility at https://mxmock.layer2financial.dev

<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({MX_WIDGET_URL})
    </script>

4. You will see the MX widget that looks something as follows in sandbox with 2 banks (MX Bank and MX Bank OAuth). In production, the end user will be able to search for their bank.

The user will select the bank, and enter their banking credentials in the screen below. Select Login as mxuser and password: P@ssword1. In Production, these would be the user's banking credentials.

As the last step, the user will have to select the bank account.

After a successful bank linking, you'll have an event fired that looks like this. Save the member_guid as you will need it for the next step.

6. Retrieve a list of linkable accounts by using the counterparties/{COUNTERPARTY_ID}/link/accounts endpoint .

Save the account_link_id for the account you want to link as you will need it for the next step

7. And finally, link the external account using the counterparties/{COUNTERPARTY_ID}/link/connect endpoint

And thats it! Your Fiat US Linked counterparty is now ready to be used in Deposits operations for an ACH pull or in ACH Withdrawal operations.

Note that you can only use a Fiat US Linked counterparty with DEPOSIT_BASIC accounts with asset type of FIAT_TESTNET_USD/FIAT_MAINNET_USD as its the only product type that supports ACH Push/Pull.