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.
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 |
|---|---|---|---|
| consumer | This object identifies the user who is making the payment and should coincide with the client's unique customer identifier as well as their first name, last name, and address | 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 explanation of the white-labeled service and contains a link to Terms and Conditions that the user inherently 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 parameter can be optionally passed with a value that matches one of the supported financial institutions. 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",
consumer: {
id: "xxxxx",
firstName: "john",
lastName: "doe",
addressStreetNumber: "100",
addressStreetName: "Commons Rd",
addressLine2: "Suite 11",
city: "Dripping Springs",
state: "TX",
zip: "78620",
country: "US"
},
showLaunchScreen: true,
onlyUseStoredCredentials: false,
fiid: "null"
},
transaction: {
id: "1234567",
total: parseFloat('5.00');,
data: 'Optional 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",
consumer: {
id: "xxxxx",
firstName: "john",
lastName: "doe",
addressStreetNumber: "100",
addressStreetName: "Commons Rd",
addressLine2: "Suite 11",
city: "Dripping Springs",
state: "TX",
zip: "78620",
country: "US"
},
showLaunchScreen: true,
onlyUseStoredCredentials: false,
fiid: "null"
},
transaction: {
id: "1234567",
total: parseFloat('5.00');,
data: 'Optional 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>