...
There is only one method call needed to add the UltraCart Hosted Credit Card Fields to your page. This static method processes the configuration and returns an instance object.
Parameters
| Argument | Type | Description |
|---|
| jQuery | jQuery | An instance of jQuery. If you're using our sample above then the value would be "jQueryHostedFields", but if you already have jQuery available on the page then you can use "jQuery" |
| JSON | JSON | An instance of the JSON object. If you are using our sample above then the value would be "jsonHostedFields". | Note |
|---|
Most browsers provide their own JSON object which can be used by the API, but including an external version as the sample above provides consistency across all browsers and versions. |
|
| config | object |
| Property | Type | Required | Description |
|---|
| sessionCredentials | Object | Yes | See SessionCredentials below. | | cssUrls | String[] | | An optional array of CSS URLs that you would like injected into the iframe to further style the hosted input. | | form | String | | An optional jQuery selector to locate the form. The underlying fields will be re-enabled before submission so that the masked values will be submitted. | | hostedFields | Object | Yes | See HostedFields below. | | overlayZIndex | Integer | | Change the default z-index for the overlay. If not specified then the overlay will use a z-index of 999999. | | autoCopyStyles | String[] | | By default, the hosted fields will copy a set of common styles from the underlying field to the input. This helps to keep fonts, colors, borders, etc. looking the same within the hosted field as the underlying field. If nothing is specified, then the default set of styles copied is: [ // Padding
"paddingBottom", "paddingLeft", "paddingRight","paddingTop",
// Text
"lineHeight", "fontSize", "fontFamily", "fontStyle", "fontWeight",
// Color
"backgroundColor", "color",
// Border
"borderBottomColor", "borderBottomLeftRadius", "borderBottomRightRadius","borderBottomStyle",
"borderBottomWidth", "borderCollapse", "borderLeftColor", "borderLeftStyle","borderLeftWidth",
"borderRightColor", "borderRightStyle", "borderRightWidth", "borderSpacing", "borderTopColor",
"borderTopLeftRadius", "borderTopRightRadius", "borderTopStyle", "borderTopWidth" ] |
|
...
| Property | Type | Required | Description |
|---|
| merchantId | String | Yes | This is the merchant ID for the UltraCart account. |
| shoppingCartToken | String | | This value is provided to the legacy checkout and the StoreFront checkout as $shoppingCartToken. |
| shoppingCartId | String | Recommended for javascript checkouts. | This is the cart.cartId for the JavaScript/REST Checkout. | Warning |
|---|
If you're using the hosted fields on a web page that's collecting credit card information for updating an existing order, or an existing auto order, do NOT provide a shoppingCartId. By leaving it off the request, the server will return back a token field that you will use to update your order/auto order record. The shoppingCartId is ONLY for placing new orders. |
|
HostedFields
| Property | Type | Required | Description | Child Properties |
|---|
| creditCardNumber | Object | Yes | Configures the credit card number field on the checkout. |
| Property | Type | Required | Description |
|---|
| selector | String | Yes | jQuery selector that identifies the original credit card number input field that will be transformed into a hosted field. | | selectorContext | Element or jQuery object | | If you need the selector to find elements within a context, populate the selectorContext property. This property along with the one above is passed to a jQuery call like jQuery(selector, selectorContext). This is typically needed only if you have a heavily dynamic page and are rendering HTML using Backbone or another JavaScript MVC framework. | | alertIfMissing | boolean | | Pop an alert if the underlying field was not found on the page. If this is false the hosted fields script will attempt to log a console message. If you ever see the error or the alert message, you are firing the setup script before the element is visible to jQuery. | | tokenSelector | String | | Optional jQuery selector that will be used to store the token received after the card is submitted. This is only necessary for simple form post checkouts where the session credentials only contains the merchant id and the values will be submitted to the UCEditor URL. | | placeholder | String | | The input fields placeholder value. If your design utilizes placeholders then you can provide it here. If the underlying input field contained a placeholder then it will automatically be read and carrier through to the hosted field. | | callback | function(card) | | An optional function that will be called with a card object after the card is submitted to the server. | | change | function() | | An optional function that can handle the change to the hosted field. The only parameter to the change function is the masked value. If no change function is provided then the default behavior is to update the underlying credit card number input field with the masked value. |
|
| creditCardCvv2 | Object | Recommended | Configured the credit card CVV2 field on the checkout. |
| Property | Type | Required | Description |
|---|
| selector | String | Yes | jQuery selector that identifies the original credit card CVV2 input field that will be transformed into a hosted field. | | selectorContext | Element or jQuery object | | If you need the selector to find elements within a context, populate the selectorContext property. This property along with the one above is passed to a jQuery call like jQuery(selector, selectorContext). This is typically needed only if you have a heavily dynamic page and are rendering HTML using Backbone or another JavaScript MVC framework. | | alertIfMissing | boolean | | Pop an alert if the underlying field was not found on the page. If this is false the hosted fields script will attempt to log a console message. If you ever see the error or the alert message, you are firing the setup script before the element is visible to jQuery. | | tokenSelector | String | | Optional jQuery selector that will be used to store the token received after the CVV2 is submitted. This is only necessary for simple form post checkouts where the session credentials only contains the merchant id and the values will be submitted to the UCEditor URL. | | placeholder | String | | The input fields placeholder value. If your design utilizes placeholders then you can provide it here. If the underlying input field contained a placeholder then it will automatically be read and carrier through to the hosted field. | | change | function() | | An optional function that can handle the change to the hosted field. The only parameter to the change function is the masked value. If no change function is provided then the default behavior is to update the underlying credit card CVV2 input field with the masked value. |
|
...
Due to the asynchronous nature of a hosted field saving its information to the server, you need to check to make sure these operations are finished before saving your cart. Otherwise you have a potential race condition between how fast the field can save the value and how quickly the customer clicks the finalize order button. This method allows you to prevent this race condition.
Parameters
| Argument | Type | Description |
|---|
| callback | function | A function to call when there are no asynchronous hosted field save operations underway. |
| Tip |
|---|
Example: var hostedFields = UltraCartHostedFields.setup(jQuery, JSON3, {/* tons of configuration here that's been omitted for brevity */});
// on your button click handler that saves the customers information, make a call to the finished method on the hosted fields
// object to make sure everything is saved before performing the cart update operation
$btn.on("click", function(){ hostedFields.finished(function(){ // Put your save code inside of this callback function }); }); |
...
The next method destory should be used to cleanup the hosted fields. If you're repainting the screen using an advanced MVC JavaScript framework then make sure you destory the UltraCartHostedFields instance, repaint the page's content, and then re-initialize a new UltraCartHostedFields instance using the setup method.
The following sections demonstrate various types of usages for the UltraCart Hosted Credit Card Fields.
Implementing UltraCart Hosted Credit Card Fields in Simple Form Post Checkouts
...