UltraCart Hosted Credit Card Fields
...
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 | 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(maskedValue) |
| 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. | | error | function(errorMessage) |
| An optional function that can handle an error message from the hosted field. The only parameter is the error message. If no error function is provided then the default behavior is to use an alert to display the message to the customer. | html5Validity | boolean |
| If set to true, the hosted field library will detect if the browser supports setCustomValidity on the input and populate it with a message when an invalid card number is provided. |
|
| 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(maskedValue) |
| 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. | | error | function(errorMessage) |
| An optional function that can handle an error message from the hosted field. The only parameter is the error message. If no error function is provided then the default behavior is to use an alert to display the message to the customer. | | callback | function(cvv2) |
| An optional function that will be called with a cvv2 object after the cvv2 is submitted to the server. The cvv2 object will contain the token and masked value. See the Cvv2 object documented below for more details. |
|
Card
| Property | Type | Description |
|---|
| maskedCreditCardNumber | String | The masked credit card number returned after the real card number is stored. |
| token | String | A token that can be passed to the UCEditor URL for simple hosted forms. |
| cardType | String | The type of card. This value can be used to select a drop box input for perform validation. |
Cvv2
| Property | Type | Description |
|---|
| maskedCreditCardCvv2 | String | The masked credit card CVV2 returned after the real card number is stored. |
| token | String | A token that can be passed to the UCEditor URL for simple hosted forms. |
The instance object returned from setup also has some additional methods that can be called.
...
Due to the asynchronous nature of the hosted field loading, we recommend that you bind your event listener before the call to UltraCartHostedFields.setup.
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
...