API Reference

Listener API

Overview

// listen to all events
psCheckout.checkoutEvent = function (data) {...};
                                          
// listen to all action events
psCheckout.checkoutAction = function (data) {...};
                                             
// listen to all update events
psCheckout.checkoutUpdated = function (data) {...};
                                              
// listen to all flow events
psCheckout.checkoutFlow = function (data) {...};
                                           
                                           
// fires each time checkoutJS client has connected with the checkout instance
psCheckout.onReady(function(){...});
                              
// fires each time checkout is rebooting
psCheckout.onLoading(function(data){...});
                                    
// fires each time checkout has completed rebooting
psCheckout.onLoaded(function(data){...});
                                   
// fires each time checkout has completed a flow
psCheckout.onComplete(function(data){...});
                                     
// fires each time checkout encounters an error
psCheckout.onError(function(data){...});

                                  
// fires the next time checkout begins rebooting
psCheckout.onceLoading(function(data){...});
                                      
// fires the next time checkout has completed rebooting
psCheckout.onceLoaded(function(data){...});

// fires the next time checkout completes a flow
psCheckout.onceComplete(function(data){...});

Event Listeners

psCheckout provides the methods that can be overridden to help filter various incoming Checkout events.

• psCheckout.checkoutEvent: This method will capture all incoming events.
• psCheckout.checkoutAction: This method will capture all event actions such as the closeDialog action.
• psCheckout.checkoutUpdated: This method will capture all update events.
• psCheckout.checkoutFlow: This method will capture all flow related events.

Event types

1. Actions: Actions are commands that are communicated between CheckoutJS and the Checkout window to perform a specific action. An example would be Checkout sending the closeDialog command to CheckoutJS so that CheckoutJS will know to hide the Checkout iframe.

2. Updates: Some modifications to checkout will update core parts of the checkout experience such as the theme or css. When these sorts of updates are detected, events of type "update" are sent.

3. Flows: Checkouts are configured with an end goal in mind. This is usually to perform a payment, tokenize a card, or scheduled a payment. Each of these is a "flow". When a payment, for example, is completed, an event of type "flow" is sent indicating that the flow has completed. This specific example would trigger the onComplete listener to fire as well.

Event Data Object

{
  "from": "paystand",
  "type": "checkoutEvent", // checkoutEvent, checkoutAction, or checkoutFlow
  "response": {
    "type": "", // various
    "flow": "", // payment, tokenize, scheduledPayment
    "object": "", // payment, token, scheduledPayment
    "data": {}, // data associated with the event
    "event": {}, // the event details
    "action": "" // the action command
  }
}

Status Listeners

When a checkout renders it goes through a series of status transitions. These different status transitions can be detected through the listener api allowing you to react to these status events.

statuses: cssLoaded, checkoutLoaded, checkoutLoading, checkoutReady, checkoutComplete, checkoutError

There are two types of listeners:

1. "on" listeners: These listeners will persistently monitor the status of checkout and will capture a status event each time checkout transitions to that particular status.

2. "once" listeners: These listeners will only capture a checkout status event on the very next occurrence of checkout transitioning to a particular status.

Checkout Actions API

Overview

// show checkout
psCheckout.showCheckout();

// hide checkout
psCheckout.hideCheckout();

// display checkout as an embed
psCheckout.embed();

// display checkout as a modal
psCheckout.modal();

// update checkout width/height
psCheckout.dimensions(width, height);


// clear current checkout settings/data and reset with provided config settings
psCheckout.reboot({...});

// keep current checkout settings/data and only update specific config settings
psCheckout.liveUpdate({...});

psCheckout.reboot

The reboot method will clear all of the current settings and data inside the checkout instance and replace it with the settings passed into the method. The final settings that the checkout instance will receive will be the merged values from the passed in settings and the settings found the the initialization <script> tag. If you require different values than those found on the script tag, then you must explicitly override them in the hash passed to the reboot method.

Once the reboot method is called, the checkout will go through the loading where the checkout loading progress bar will appear until the reboot is complete and the checkout changes to the loaded status.

psCheckout.liveUpdate

The liveUpdate method will update data in the checkout instance directly without causing the checkout instance to go through a reboot process. No status transitions will occur, no progress loading bars will appear, and no status listeners will fire. Depending on what settings are updated during the live update command, one or more event listeners may fire.