Skip to content

External Accounts Guide

This external accounts guide assumes that you have already completed the TheM>Getting Started>Quick Start guide and are familiar with TheM class, TheM submodule initialization, and creating/listening for custom events. This guide also assumes that you have already installed the amplifi_mobile_sdk package into your project and placed the following minified libraries in the /lib folder of your project: axios.min.js (Optional - fetch will be used if axios is not present), crypto-js.min.js, lz-string.min.js, moment.min.js, and socket.io.min.js. In addition, you should have completed the Onboarding Guide tutorial in order to create and onboard a user which can be logged into your ampliFi instance.

1. In the src folder of your project (from the Quick Start guide of the TheM Getting Started section), create a new file called externalAccounts.js with the following code.

externalAccounts.js

import ClassTheM from "../node_modules/@PayGearsCorp/amplifi_mobile_sdk/TheM/them.mjs";

import { thisDevice } from "./android-demo-device.js"; //android device emulator for testing

const AMPLIFI_BASE_URL = "PUT_YOUR_INSTANCE_URL_HERE"; //Speak to a PayGears representative to be issued a sandbox instance URL
const AMPLIFI_CORE_URL = `${AMPLIFI_BASE_URL}core/`;
const DEVICE_TAG = "PUT_YOUR_DEVICE_TAG_HERE"; //Use deviceTag obtained from onboarding tutorial for this device

const subClassesToInit = [
    "common",
    "user",
    "accounts",
    "cards",
    //"statics",
    //"beneficiaries",
    //"cheques",
    "externalAccounts",
    //"fdrs",
    //"fundstransfer",
    //"fxrates",
    //"genericRequests",
    //"ious",
    //"onboarding",
    //"payees",
    //"remittance",
    //"restrictions",
];


export const externalAccountsTutorial = async (subClasses = "") => {
    TheM = new ClassTheM({
        config: {
            AFiInstanceId: "test",
            modulesFolder: "",
            modulesFolderOnboarding: "",
            webworkerFolder: "../TheM/",
            baseLibURL: "../demo/lib/",
            backEndURL: AMPLIFI_CORE_URL,
            socketURL: AMPLIFI_BASE_URL,
        },
        libs: {
        }
    });

    //Emulate user device before initializing TheM submodules
    TheM.thisDevice = {
        ...thisDevice,
        TheM,
        deviceTag: DEVICE_TAG,
    };

    //Initialize desired submodules
    //Some modules depend on others so must be initialized together
    //For instance, most submodules require the "common" subclass to be initialized
    await TheM.doInit(subClasses);

    //externalAccounts workflow to try
    //Uncomment to run the whole workflow or follow the instructions in the browser
    /*
    //Prepare for logging in
    //Log in using the instructions in the browser or use the doAuthenticate method from the device emulator we created during onboarding
    await TheM.thisDevice.doAuthenticate(DEVICE_TAG);

    //Pull externalAccounts data from the server if it is not fresh enough
    await TheM.externalAccounts.doUpdate();

    console.log(`TheM.externalAccounts.isReady: ${JSON.stringify(TheM.externalAccounts.isReady)}`)

    let newExternalAccountDebitCard = {
        type: 'DEBITCARD',
        pan: '4005519200000004',
        cvv: '123',
        expiryYYYYMM: '202610',
        name_on_card: 'SUZY QUEUE TESTER',
        expiryYY: '26',
        expiryMM: '10',
        comment: 'Individual debit card',
        name: 'Individual debit card2',
        title: 'Suzy Tester',
        cardImageFront: 'Very_Long_B64_Image_String',
        cardImageBack: 'Very_Long_B64_Image_String',
        networkName: 'Visa',
        dtsModified: new Date()
    };

    let newExternalAccountBankAccount = {
        type: 'CHECKING',
        accountNumber: '123467890123456',
        routingNumber: '103112617',
        bankName: 'Bank ABC',
        comment: 'Bank Account',
        name: 'Bank Account2',
        title: 'Suzy Tester',
        dtsModified: new Date()
    };

    //add new bank account external account
    await TheM.externalAccounts.push(newExternalAccountDebitCard);
    //add new debit card external account
    await TheM.externalAccounts.push(newExternalAccountBankAccount);

    //pull money from most recently added external account
    let isValidPull = await TheM.externalAccounts[TheM.externalAccounts.length - 1].isPullValid({ "amount": 20.00, "currency": "USD" });
    if (isValidPull) {
        console.log("Pulling funds from external account.")
        await TheM.externalAccounts[TheM.externalAccounts.length - 1].doPull({ "amount": 20.00, "currency": "USD" });
    } else {
        console.log("Pull is not valid.")
    }

    //push money to most recently added external account
    let isValidPush = await TheM.externalAccounts[TheM.externalAccounts.length - 1].isPushValid({ "amount": 1.01, "currency": "USD" });
    if (isValidPush) {
        console.log("Pushing funds to external account.")
        await TheM.externalAccounts[TheM.externalAccounts.length - 1].doPush({ "amount": 1.01, "currency": "USD" });
    } else {
        console.log("Push is not valid.")
    }

    //set up autofunding
    TheM.externalAccounts.autofunding.AFiExternalAccountId = TheM.externalAccounts[TheM.externalAccounts.length - 1].AFiExternalAccountId;
    TheM.externalAccounts.autofunding.amount = 20.00;
    TheM.externalAccounts.autofunding.currency = "USD";
    TheM.externalAccounts.autofunding.cadence = "when_low";
    TheM.externalAccounts.autofunding.lowAmount = 15.00;

    //if autofunding set up is valid, then TheM.externalAccounts.autofunding.isEnabled will return true
    console.log(`TheM.externalAccounts.autofunding.isEnabled: ${JSON.stringify(TheM.externalAccounts.autofunding.isEnabled)}`)


    //Logout when finished
    //await TheM.user.doLogout();
    */
};

await externalAccountsTutorial(subClassesToInit.join(" "));
  1. The externalAccounts module expects the user to be using some type of device so make sure the android-demo-device.js file used during onboarding is still in your /src folder.

  2. Create a new file in the /demo folder of your project called externalAccounts.html with the following code.

externalAccounts.html

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />

    <title>ampliFi</title>

    <script>
        var TheM;
        var TheM_config;
    </script>

    <script src="../lib/socket.io.min.js"></script>
    <script src="../lib/lz-string.min.js"></script>
    <script src="../lib/moment.min.js"></script>
    <script src="../lib/axios.min.js"></script>
    <script src="../lib/crypto-js.min.js"></script>
    <script type="module" src="/../src/externalAccounts.js"></script>

    <style>
        html {
            color: white;
            background-color: black;
        }
    </style>
</head>


<body>
    <div>
        Hit F12 to open the browser console.
        Start working with TheM by typing "TheM" into the browser console.
    </div>
    <br />
    <br />
    <div>
        1. In order to log a user in, we will need to prepare the user credentials using the encryptedServerSecret
        stored locally during onboarding. Type the following to retrieve the encryptedServerSecret. (Or skip steps 1-5
        by using the doAuthenticate method in the device emulator like so, `await
        TheM.thisDevice.doAuthenticate(DEVICE_TAG);`.)
        <br /><br />
        <code>let { encryptedServerSecret } = await TheM.thisDevice.retrieveLocally("encryptedServerSecret", true);</code>
        <br /><br />
        Type <code>encryptedServerSecret</code> into the browser console and hit enter to view the encryptedServerSecret
        value.
        <br /><br />
        2. Since we are using an emulated android device to log in, we need to get the cryptotext value like so.
        <br /><br />
        <code>
            let _SUPER_SECRET = "0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000";<br />
            let _dtsValueString = (new Date()).valueOf().toString();<br />
            let serverSecret = CryptoJS.AES.decrypt(encryptedServerSecret, _SUPER_SECRET).toString(CryptoJS.enc.Utf8);<br />
            let cryptotext = CryptoJS.AES.encrypt((TheM.thisDevice.deviceTag) + _dtsValueString, serverSecret).toString(); 
        </code>
        <br /><br />
        3. Set a socket connection for bidirectional communication.
        <br /><br />
        <pre><code>TheM.thisDevice.halfRef = TheM.common.GetRandomSTR(40);<br />let manager = new TheM.io.Manager(TheM.config.socketURL + "?halfRef=" + TheM.thisDevice.halfRef, {<br />  autoConnect: false<br />});<br />let socket = manager.socket("/");</code></pre>
        <br />
        4. Open the socket connection.
        <br /><br />
        <pre><code>manager.connect(function (data) {<br />  console.log("established real-time comm channel for onboarding");<br />  TheM.thisDevice.isRealTimeCommAvailable = true;<br />});</code></pre>
        <br />
        5. Log the user in using the deviceTag obtained during onboarding and the newly created cryptotext.
        <br /><br />
        <pre><code>const credentials = {<br />  "dtsValueString": _dtsValueString,<br />  "deviceTag": "PUT_DEVICE_TAG_HERE",<br />  "deviceData": TheM.thisDevice.data,<br />  "channel": TheM.thisDevice.platform,<br />  "dynamicScreensVersion": TheM.thisDevice.dynamicScreensVersion,<br />  "socket": {<br />    halfRef: TheM.thisDevice.halfRef<br />  },<br />  "pushMessToken": TheM.thisDevice.pushMessToken,<br />  "cryptotext": cryptotext<br />};<br />await TheM.user.doLogin(credentials);</code></pre>
        <br />
        6. After authentication, the locally stored data should be automatically loaded. You can check to see if the
        externalAccounts submodule is fully ready like so.
        <br /><br />
        <code>
            TheM.externalAccounts.isReady;
        </code>
        <br /><br />
        7. Pull externalAccounts data from the server if it is not fresh enough.
        <br /><br />
        <code>await TheM.externalAccounts.doUpdate();</code>
        <br /><br />
        8. You can add a new external account using TheM.externalAccounts.push(given), where the given object contains
        the external account properties.
        <br />
        <pre><code>let newExternalAccountDebitCard = {<br />  type: 'DEBITCARD',<br />  pan: '4005519200000004',<br />  cvv: '123',<br />  expiryYYYYMM: '202610',<br />  name_on_card: 'SUZY QUEUE TESTER',<br />  expiryYY: '26',<br />  expiryMM: '10',<br />  comment: 'Individual debit card',<br />  name: 'Individual debit card2',<br />  title: 'Suzy Tester',<br />  cardImageFront: 'Very_Long_B64_Image_String',<br />  cardImageBack: 'Very_Long_B64_Image_String',<br />  networkName: 'Visa',<br />  dtsModified: new Date()<br />};<br />await TheM.externalAccounts.push(newExternalAccountDebitCard);<br />await TheM.externalAccounts.doUpdate();</code></pre>
        <br />
        9. You can check to see if a pull is possible for the external account that was most recently added like so.
        (Check to see if a push is possible by using .isPushValid instead.)
        <br /><br />
        <code>await TheM.externalAccounts[TheM.externalAccounts.length - 1].isPullValid({ "amount": 20.00, "currency": "USD" });</code>
        <br /><br />
        10. Pull funds from the most recently added external account into the user's main or first account in ampliFi.
        <br /><br />
        <code>await TheM.externalAccounts[TheM.externalAccounts.length - 1].doPull({ "amount": 20.00, "currency": "USD" });</code>
        <br /><br />
        11. Set up autofunding, if desired.
        <br />
        <pre><code>TheM.externalAccounts.autofunding.AFiExternalAccountId = TheM.externalAccounts[TheM.externalAccounts.length - 1].AFiExternalAccountId;<br />TheM.externalAccounts.autofunding.amount = 20.00;<br />TheM.externalAccounts.autofunding.currency = "USD";<br />TheM.externalAccounts.autofunding.cadence = "when_low";<br />TheM.externalAccounts.autofunding.lowAmount = 15.00;<br /><br />//if autofunding set up is valid, then TheM.externalAccounts.autofunding.isEnabled will return true<br />console.log(`TheM.externalAccounts.autofunding.isEnabled: ${JSON.stringify(TheM.externalAccounts.autofunding.isEnabled)}`)</code></pre>
        <br />
        12. Keep exploring TheM.externalAccounts properties and methods and log out when finished.
        <br /><br />
        <code>
            await TheM.user.doLogout();
        </code>
        <br /><br />
    </div>
</body>

</html>

6. Start a server in the root folder of your project.

py -m http.server 8000

7. Open a browser and enter the following URL: http://localhost:8000/demo/

8. Click on the link for "externalAccounts.html" and follow the instructions to log in, create a new external account, pull from an external account, set up autofunding, and log out.