...
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. |
| creditCardCvv2 | Object | Recommended | Configured the credit card CVV2 field on the checkout. | | Property | Type | Required | 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 | 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
| 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. |
|
Card
| 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. |
|
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. |
...
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
...
| Code Block |
|---|
| language | javascript |
|---|
| theme | DJango |
|---|
|
// as a reminder, jQueryHostedFields is a reference to a jQuery object.
// The CSS style of the hosted fields will mimic the underlying fields, so for example, if you
// change the credit card field to have a red background, then the hosted fields will also change to red.
jQueryHostedFields("#cardNumber").on('change', function(){
// When a change occurs, the //hosted Clearfield existinglibrary classeswill add one of three classes jQueryHostedFields("#cardNumber").removeClass("noCreditCardNumber");
jQueryHostedFields("#cardNumber").removeClass("validCreditCardNumber");
jQueryHostedFields("#cardNumber").removeClass("invalidCreditCardNumber");
// Regex for basic validation of a masked Amex or other 16 digit card.
var re = /[X]{4}-[X]{6}-X[0-9]{4}|[X]{4}-[X]{4}-[X]{4}-[0-9]{4}/i;
// Test to see if the field is empty, appears valid or is invalidto the underlying input: noCreditCardNumber, invalidCreditCardNumber, validCreditCardNumber
var fieldValue =if (!jQueryHostedFields(this).val(); if (fieldValue === "") {|| jQueryHostedFields(this).hasClass("noCreditCardNumber")) {
jQueryHostedFields("#cardNumber").addClass("noCreditCardNumber");
} else if (re.test(fieldValue)) {
// No value in the credit card field
}
if (jQueryHostedFields("#cardNumber"this).addClasshasClass("validCreditCardNumberinvalidCreditCardNumber");) {
} else {// The value in the credit card field jQueryHostedFields("#cardNumber").addClass("invalidCreditCardNumber");is invalid
}
});
jQueryHostedFields("#cvv2").on('change', function(){
// Clear existing classes
jQueryHostedFields("#cvv2").removeClass("noCreditCardCvv2");
jQueryHostedFields("#cvv2").removeClass("validCreditCardCvv2");
jQueryHostedFields("#cvv2").removeClass("invalidCreditCardCvv2");
// Regex for basic validation of a masked CVV2 value.
var re = /[X]{3,4}/i;
// Test to see if the field is empty, appears valid or is invalid
var fieldValue = jQueryHostedFields(this).val();
if (fieldValue === "") {
jQueryHostedFields("#cvv2").addClass("noCreditCardCvv2");
} else if (re.test(fieldValue)) {
jQueryHostedFields("#cvv2").addClass("validCreditCardCvv2");
} else {
jQueryHostedFields("#cvv2").addClass("invalidCreditCardCvv2");
}
});
// Perform initial validation
jQueryHostedFields("#cardNumber,#cvv2").trigger("change"); |
...