Payees Guide
This payees 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 payees.js with the following code.
payees.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 support 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 = [
"accounts",
"beneficiaries",
"cards",
//"cheques",
"common",
//"externalAccounts",
//"fdrs",
//"fundstransfer",
//"fxrates",
//"genericRequests",
//"ious",
//"onboarding",
"payees",
//"remittance",
//"restrictions",
//"statics",
"user"
];
export const payeesTutorial = 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);
//payees 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 data from the server if it is not fresh enough
await TheM.beneficiaries.doUpdate();
await TheM.payees.doUpdate();
console.log(`TheM.beneficiaries.isReady: ${JSON.stringify(TheM.beneficiaries.isReady)}`);
console.log(`TheM.payees.isReady: ${JSON.stringify(TheM.payees.isReady)}`);
//Create a beneficiary that will be added to the payee group
const newACHBeneficiary = TheM.beneficiaries.newTempBeneficiary("USA", {
txnType: "USA",
name: "ACH Payee",
accountNumber: "1234567890123456",
bankName: "Citibank NA",
destinationName: "Receiving account title",
routingNumber: "123456789",
defaultAmount: 20,
narrativeDebit: "ACH payment",
isFavourite: true,
type: "CHECKING"
});
await newACHBeneficiary.doSubmit({});
//Create a payee group
const newPayee = TheM.payees.newTempPayee({
name: "Payee Name",
isFavourite: false,
isHidden: false,
imageBase64: "VeryLongBase64ImageString",
narrativeDebit: "A brief narrative",
narrativeCredit: "A brief narrative",
isBusiness: false
});
await newPayee.doSubmit({});
//Assign the beneficiary that you created to the new payee group. You may add multiple beneficiaries to the same payee group.
TheM.beneficiaries[TheM.beneficiaries.length - 1].AFiPayeeId = TheM.payees[TheM.payees.length - 1].AFiPayeeId;
//Logout when finished
//await TheM.user.doLogout();
*/
};
await payeesTutorial(subClassesToInit.join(" "));
2. The payees 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.
3. Create a new file in the /demo folder of your project called payees.html with the following code.
payees.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/payees.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
beneficiaries and payees submodules are fully ready by calling the .isReady property of each submodule. (Since a
payee is a group of beneficiaries, you
will need both of these submodules.)
<br /><br />
<code>
console.log(TheM.beneficiaries.isReady);<br />console.log(TheM.payees.isReady);
</code>
<br /><br />
7. Pull beneficiaries and payees data from the server if it is not fresh enough.
<br /><br />
<code>await TheM.beneficiaries.doUpdate();<br />await TheM.payees.doUpdate();</code>
<br /><br />
8. You can create a new beneficiary using a TheM.benficiaries.newTempBeneficiary(givenTxnType, given) call where
givenTxnType is the beneficiary transaction type and given is an object containing all required beneficiary
properties for the specified transaction type. You may create multiple beneficiaries to add to a single payee
group if desired.
<br />
<pre><code>const newACHBeneficiary = TheM.beneficiaries.newTempBeneficiary("USA", {<br /> txnType: "USA",<br /> name: "ACH Payee",<br /> accountNumber: "1234567890123456",<br /> bankName: "Citibank NA",<br /> destinationName: "Receiving account title",<br /> routingNumber: "123456789",<br /> defaultAmount: 20,<br /> narrativeDebit: "ACH payment",<br /> isFavourite: true,<br /> type: "CHECKING"<br />});<br />await newACHBeneficiary.doSubmit({});</code></pre>
<br />
9. Next, create a new payee group.
<br />
<pre><code>const newPayee = TheM.payees.newTempPayee({<br /> name: "Payee Name",<br /> isFavourite: false,<br /> isHidden: false,<br /> imageBase64: "VeryLongBase64ImageString",<br /> narrativeDebit: "A brief narrative",<br /> narrativeCredit: "A brief narrative",<br /> isBusiness: false<br />});<br />await newPayee.doSubmit({});</code></pre>
<br />
10. Add the recently created beneficiary to the new payee group by assigning the payee AFiPayeeId to the
beneficiary.
<br /><br />
<code>TheM.beneficiaries[TheM.beneficiaries.length - 1].AFiPayeeId = TheM.payees[TheM.payees.length - 1].AFiPayeeId;</code>
<br /><br />
11. Keep exploring TheM.payees properties and methods and log out when finished.
<br /><br />
<code>
await TheM.user.doLogout();
</code>
<br /><br />
</div>
</body>
</html>
4. Start a server in the root folder of your project.
5. Open a browser and enter the following URL: http://localhost:8000/demo/
6. Click on the link for "payees.html" and follow the instructions to log in, add a new beneficiary, add a new payee group, assign the beneficiary to the payee group, and log out.