Money API™ Documentation

Checkout 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, the "CLIENT_ID" is for reference only and should be replaced with the client ID provided to you by AppBrilliance.

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

Initialization

The first step in starting a transaction is to initialize the service. This is achieved by invoking the appbClient.initialize() function which requires the specification of two IDs:

Item Description Format Required
consumerId This identifies the user who is making the payment and should coincide with the client's unique customer identifier. varchar(255) 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

Checkout

Once the initialize function has been properly invoked, the appbClient.checkout() function may be run to conduct a transaction. The checkout function needs to be executed as part of a callback to the appbClient.initialize() function and will launch an iframe that will guide the user through the transaction process. This function requires the specification of additional data as part of a "transaction" object that is related to a specific transaction. The data is as follows:

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. N/A
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. code
message

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 alert().


<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 src="https://sdk.securenet.live/appb-client-ui.0.1.js?clientId=CLIENT_ID"></script>
    </head>
    <body>
        <button id="checkoutButton">Checkout</button>
        <script>
            $(document).ready(function() {
                appbClient.initialize(
                    {
                        consumerId: 'CLIENT_CONSUMER_ID',
                        merchantId: 'MERCHANT_ID'
                    },
                    function() {
                        $("checkoutButton").on("click", function() {       
                            appbClient.checkout({
                                transaction: {
                                    id: 'CLIENT_TRANSACTION_ID',
                                    total: 5.00,
                                    data: 'THIS IS SAMPLE EXTRA DATA'
                                },
                                onSuccess: function(data) {
                                    alert('The payment completed successfully.  The AppBrilliance transaction ID is: ' + data.transactionId);
                                },
                                onCancel: function(data) {
                                    alert('The user canceled the payment.')
                                },
                                onError: function(data) {
                                    alert('Error code: ' + data.code + '. ' + data.message);
                                }
                            });
                        });
                    }
                );
            });
          </script>
    </body>
</html>