Money API™ Documentation

Money API™ Integration

Once you have the assigned IDs and API key(s) from AppBrilliance, you’re ready to begin Money API™ integration and testing. This document will walk through the various requirements and examples of how to integrate Money API™ into a standard HTML page.

Best Practice: Pre-Transaction Amount Validation

Due to payment limits set by financial institutions, the Money API™ should only be presented as a payment option for transactions that are greater than $1.00 and less than or equal to $3,500.00 at this time. Doing this check at the point payment options are presented will promote a better user experience.

The Money API™ Script Tag

The first step in integrating Money API™ into an HTML page is to place the script tag in the <HEAD> portion of the HTML. The following illustrates a proper script tag integration with a required id value of "appb-script". The "CLIENT_ID" value is for reference only and must be replaced with the client ID provided to you by AppBrilliance.

Sample Implementation of Script Tag

<script id='appb-script' src="https://sdk.securenet.live/appb-client-ui.0.1.js?clientId=CLIENT_ID"></script>

Checkout Function

The checkout function is required in order to transfer funds. Proper execution of the checkout function will inject an iframe into the host page and launch a modal that will guide the user through the transaction process. The checkout function requires the specification of an "options" object and a "transaction" object that communicate information about the merchant, user, and transaction. The data is as follows:

Options Object

Item Description Format Required
consumerId This identifies the user who is making the payment and should coincide with the client's unique customer identifier.   YES
merchantId This identifies the merchant the consumer is making a payment to. This must be a pre-configured identifier that AppBrilliance has associated to the "clientId" that is defined in the script tag. varchar(255) YES
showLaunchScreen This will have a value of true or false. When set to true, the user will be presented with a custom screen that contains an explination of the white-labeled service and contains a link to Terms and Conditions that the user inherantly agrees to prior to continuing with a payment. When not specified the system will proceed with a default value of false. true or false NO
onlyUseStoredCredentials This option is designed for use when the checkout function is being used in concert with the linkAccount function which will store the needed data to invoke a payment. When set to true, the user will not be prompted for login or shown the optional launch screen. true or false NO
fiid This paramater can be optionally passed with a value that matches one of the supported financial institutions (boa, capital-one, chase, citibank, wellsfar). When a recognized FIID value is passed in, the login screen will replace the bank selector and instructive text with the logo of the corresponding FIID. Passing in an unrecognized FIID will result in the user having to select their FI on the login screen TEXT NO

Transaction Object

Item Description Format Required
id This is the client's unique identifier for a given transaction. varchar(64) YES
total This is the total amount in USD that is to be paid by the consumer. This amount is specified without the "$". For example, "$10.00" would be specified as "10.00" Numeric value only with two decimal places YES
data This is not required but is open to have additional information submitted that will be available when retrieved via the Transactions API. blob/longtext
(will be base64 encoded)
NO

Checkout Event Handlers

There are three event handlers that can be invoked by the appbClient.checkout() function. Below is a list of the event handlers and a description of their purpose.

Handler Description Returns
onSuccess Invoked only when a transaction has successfully completed. The data returned is AppBrilliance's unique transaction ID. transactionId
onCancel Invoked when a user elects to cancel the payment via the payment confirmation step or closes the user experience. There is no data returned to this event handler. It is possible to restart a transaction again by re-invoking the appbClient.checkout() function. no data is returned
onError Invoked when a programmatic error or timeout occurs. This handler receives a data object that contains an error code and an error message. It is recommended that an alternative payment option be presented to the user should an onError event occur. error code,
error message

Sample Implementation of Checkout Function

                    
    $("#checkoutButton").on("click", function() {
        appbClient.checkout({
            options: {
                merchantId: "xxxxx",
                consumerId: "xxxxx",
                showLaunchScreen: true,
                useOnlyStoredCredentials: false,
                fiid: "null"
            },
            transaction: {
                id: "1234567",
                total: parseFloat('5.00');,
                data: 'Opional Extra Data'
            },
            onSuccess: function(data) {
                var transactionId = data.transactionId ? data.transactionId : "";
                console.log('Payment Successful - Transaction ID: ' + transactionId);
            },
            onError: function(error) {
                if (error) {
                var msg = error.code + ': ' + error.message;
                console.error('Error: ', msg);
                }
            },
            onCancel: function() {
                console.warn('User cancelled transaction');
            }
        });
    });
    

                    

Full Example Implementation

The following shows an example implementation where the appbClient.initialize() is invoked through a jQuery ready() function and the appbClient.checkout() function is invoked through an onClick() event. All three event handlers for the appbClient.checkout() function present a corresponding console message.


<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.0.0/jquery.min.js"></script>      
        <script id='appb-script' src="https://sdk.securenet.live/appb-client-ui.0.1.js?clientId=CLIENT_ID"></script>
        <script>
        $(document).ready(function() {
            $("#checkoutButton").on("click", function() {
                appbClient.checkout({
                    options: {
                        merchantId: "xxxxx",
                        consumerId: "xxxxx",
                        showLaunchScreen: true,
                        useOnlyStoredCredentials: false,
                        fiid: "null"
                    },
                    transaction: {
                        id: "1234567",
                        total: parseFloat('5.00');,
                        data: 'Opional Extra Data'
                    },
                    onSuccess: function(data) {
                        var transactionId = data.transactionId ? data.transactionId : "";
                        console.log('Payment Successful - Transaction ID: ' + transactionId);
                    },
                    onError: function(error) {
                        if (error) {
                        var msg = error.code + ': ' + error.message;
                        console.error('Error: ', msg);
                        }
                    },
                    onCancel: function() {
                        console.warn('User cancelled transaction');
                    }
                });
            });  
        });   

      </script>
    </head>
    <body>
        <button id="checkoutButton">Checkout</button>
    </body>
</html>

Link Function

The Link function is not required to run a transaction. The link function is designed to fit workflows that establish a link to a financial institution prior to a funding or payment event. This primary difference between the link and checkout functions is that the "remember me" option is automatically utilized with the link function and it doesn't require an amount or transaction information as it does not conduct a transaction.

Options Object

Item Description Format Required
consumerId This identifies the user who is making the payment and should coincide with the client's unique customer identifier.   YES
merchantId This identifies the merchant the consumer is making a payment to. This must be a pre-configured identifier that AppBrilliance has associated to the "clientId" that is defined in the script tag. varchar(255) YES
showLaunchScreen This will have a value of true or false. When set to true, the user will be presented with a custom screen that contains an explination of the white-labeled service and contains a link to Terms and Conditions that the user inherantly agrees to prior to continuing with a payment. When not specified the system will proceed with a default value of false. true or false NO
fiid This paramater can be optionally passed with a value that matches one of the supported financial institutions (boa, capital-one, chase, citibank, wellsfar). When a recognized FIID value is passed in, the login screen will replace the bank selector and instructive text with the logo of the corresponding FIID. Passing in an unrecognized FIID will result in the user having to select their FI on the login screen TEXT NO

Link Event Handlers

There are three event handlers that can be invoked by the appbClient.checkout() function. Below is a list of the event handlers and a description of their purpose.

Handler Description Returns
onSuccess Invoked only when a link has successfully completed.  
onCancel Invoked when a user elects to close the application. There is no data returned to this event handler. It is possible to restart a link again by re-invoking the appbClient.link() function. no data is returned
onError Invoked when a programmatic error or timeout occurs. This handler receives a data object that contains an error code and an error message. It is recommended that an alternative funding option be presented to the user should an onError event occur. error code,
error message

Sample Implementation of Checkout Function

                    
    $("#linkButton").on("click", function() {
        appbClient.link({
            options: {
                merchantId: "xxxxx",
                consumerId: "xxxxx",
                showLaunchScreen: true,
                fiid: "null"
            },
            onSuccess: function(data) {
                console.log('The user has successfully linked to their bank account.');
            },
            onError: function(error) {
                if (error) {
                var msg = error.code + ': ' + error.message;
                console.error('Error: ', msg);
                }
            },
            onCancel: function() {
                console.warn('User cancelled the link.');
            }
        });
    });
    

                    

Full Example Implementation

The following shows an example implementation where the appbClient.initialize() is invoked through a jQuery ready() function and the appbClient.checkout() function is invoked through an onClick() event. All three event handlers for the appbClient.checkout() function present a corresponding console message.


<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.0.0/jquery.min.js"></script>      
        <script id='appb-script' src="https://sdk.securenet.live/appb-client-ui.0.1.js?clientId=CLIENT_ID"></script>
        <script>
        $(document).ready(function() {
            $("#linkButton").on("click", function() {
                appbClient.link({
                    options: {
                        merchantId: "xxxxx",
                        consumerId: "xxxxx",
                        showLaunchScreen: true,
                        fiid: "null"
                    },
                    onSuccess: function(data) {
                        console.log('The user has successfully linked to their bank account.');
                    },
                    onError: function(error) {
                        if (error) {
                        var msg = error.code + ': ' + error.message;
                        console.error('Error: ', msg);
                        }
                    },
                    onCancel: function() {
                        console.warn('User cancelled the link.');
                    }
                });
            });
        });   

      </script>
    </head>
    <body>
        <button id="linkButton">Link Account</button>
    </body>
</html>