MX enables applications to connect with users' bank, credit card, loan, and investment accounts, to pull in account details such as balances and transactions.

Setup

To get started, you'll first need to sign up with MX, if you aren't yet a user. Once on the MX developer portal, follow the instructions below:

1. Copy the MX-Client-ID and paste it into the Hydrogen Admin Credentials screen as the "Username/Client Id" for MX.
2. Copy the MX-API-Key and paste it into the Hydrogen Admin Credentials screen as the "Password/Client Secret" for MX.
3. Choose MX as the vendor for financial account aggregation under the "Aggregation" tab of the Hydrogen Admin Settings.
4. On the same screen, enter your "Webhook User" and "Webhook Secret" that you created on the MX Developer Portal. We will use these values to validate the requests.

MX Connect

Once you have MX credentials set up on the Integrations Admin, you can embed MX Connect into your app or web page. The MX Connect will manage user credential validation, multi-factor authentication, and error handling for each institution that MX supports to ensure that your end-user is able to pull data from the account that they've linked.

Below is a sample MX Connect link embed code.

 
<script src="https://atrium.mx.com/connect.js"></script> 
<script>  
     var mxConnect = new MXConnect({    
          id: 'addAccount',    
          url: '<link>',
          onLoad: function () {  // Connect widget successfully loaded
          console.log('On Load');    
     },
     onSuccess: function (memberGuid) {  // Member created successfully
          console.log('On Success');    
     }  
     }); 
     var addAccountClick = function () {
          mxConnect.load();  
     }; 
</script> ​ 
 

Implementation

User Creation

Create a user in MX for the client_id that was created in Nucleus. This will connect the Hydrogen user to the MX user. This process can also be automated through the Hydrogen Integration Admin settings if you wish to use MX for all clients that you sign up:

POST /integration/v1/user

Sample Request

 
{
    "nucleus_client_id": "<nucleus_client_id>",
    "product": "atom",
    "integration_type": "aggregation",
    "vendor_name": "mx"
}

Account Aggregation

You will need to retrieve the URL for the client and replace the url in the widget above with it. To replace this, you can use the following Hydrogen endpoint to get the latest URL:

GET /integration/v1/widget_link/{nucleus_client_id}?vendor_name=mx

Sample Response

 
{
    "widget_url": "https://int-widgets.moneydesktop.com/md/connect/6xjA9mcj32ps626s2flqlAz8nyZgfgmz5dlc0gfyhqqm6kt05f0lhc6wlynpy5m2knkk92pmsr2j30vyszA14gbppmzdcmbv7rsjrA0n4c3mfyptq6qr1kjlbc9f40nA6clgs04rcsdjj8dbl0h43zt7xw9b3rzml71c22xd0f4mzvqAcldAh49tsgfwqp97ctxqmzjvzk0rq51rmg0xmy8Al3ktysntstfq9h1zmzh39288lw910z3l2xr0vv093xcqj877b35gr9zp68w338r3hb5pAzjdqc3r0wcbcszfs60670yt0zcg1xzp60lrs9b0qq9cjc44A0607m3nzdmw3ll1bAr18mw9kf41/eyJ1aV9tZXNzYWdlX3ZlcnNpb24iOjEsInVpX21lc3NhZ2Vfd2Vidmlld191cmxfc2NoZW1lIjoiYXRyaXVtIn0%3D",
    "vendor_name": "mx"
}
 

In the response, use the widget_url and replace the url in the MX widget code above. Now, the code snippet is ready to launch the MX Connect applet.

Now we just have to create the aggregation account to store all the data in Nucleus from the response above. Make sure you submit the call below in the onSuccess() function of the MX Connect UI widget above.

POST /integration/v1/aggregation/account

  
{
     "nucleus_client_id": "<nucleus_client_id>",
     "product": "atom" 
}  

The result above will create an aggregation_account_id in Nucleus. If you select "Automatically retrieve the latest balance, transactions and holdings after initial Aggregation Account creation" in the Integration Admin Settings, this data will pull in once the account is stored. Otherwise, you can perform the following calls to pull various account data:

GET /integration/v1/aggregation/balance/{aggregation_account_id}

GET /integration/v1/aggregation/transaction/{aggregation_account_id}

GET /integration/v1/aggregation/holding/{aggregation_account_id}

Webhooks

After submitting your MX credentials, Hydrogen will automatically register callback URLs for webhooks on your behalf. All we need is the Webhook Username and Webhook Secret that you set up in the MX developer portal. Please follow the instructions listed in the initial setup. We have integrated all events offered by MX for the following data, so you can sit back and watch the data automatically populate in Nucleus!

Balances

Transactions

Instant Account Verification (IAV)

Please see user creation before you may verify a bank account.

You will need to retrieve the URL for the client and replace the url in the widget above with it. To retrieve an IAV link please set the mode parameter to "iav" which differs from the aggregation link:

GET /integration/v1/widget_link/{nucleus_client_id}?vendor_name=mx&mode=iav

Sample Response

 
{
    "widget_url": "https://int-widgets.moneydesktop.com/md/connect/b9flqrld7ynpm7w4qfpgs83223Zrmk4pw7frf0v9d5r74j39hsy6r18y9brsq27p3jmlntcmtkqfhg1bb1nflphbbsyA47Akw33k0gAf9pAhj06j0dcghrv378lx60b40prw2m3qr89ckzm7hxmp047jyr0mw2A5pqb2ymty9dzqwr940p96cmgw3t3tp53ln80ggd2g7z1lv258q5wf09rzzpvsjqnzdlxx8779kt6gkw19b07gjrg2xd5w4m3bg6vm3v02t6sgsAkAldA0n3f5d76r0gmgr08fy2r8drrx9483pkrl8k6rl0s0gb6cvvp6fA0xvj66p1x9kkrs544894g713q1z2b01tnq/eyJ1aV9tZXNzYWdlX3ZlcnNpb24iOjEsInVpX21lc3NhZ2Vfd2Vidmlld191cmxfc2NoZW1lIjoiYXRyaXVtIiwibW9kZSI6InZlcmlmaWNhdGlvbiJ9",
    "vendor_name": "mx"
}
 

If you wish to use MX for verifying bank accounts, you now can attach a verified bank_link_id in Nucleus to the MX account created, using the member_id from the onSuccess: function (memberGuid) {} function in the widget link response.

POST /integration/v1/iav

{
    "nucleus_client_id": "<nucleus_client_id>",
    "product": "atom",
    "vendor_request": {
        "member_id": "<member_id from MX account link response>"
    }
}