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
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:
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/{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 10 months ago