Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Added Ionic framework section.

Table of Contents

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

ArgumentTypeDescription
jQueryjQueryAn 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"
JSONJSON

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.


configobject


PropertyTypeRequiredDescription
sessionCredentialsObjectYesSee SessionCredentials below.
cssUrlsString[]
An optional array of CSS URLs that you would like injected into the iframe to further style the hosted input.
formString
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.
hostedFieldsObjectYesSee HostedFields below.
overlayZIndexInteger
Change the default z-index for the overlay. If not specified then the overlay will use a z-index of 999999.
autoCopyStylesString[]

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"

 ]


...

PropertyTypeRequiredDescriptionChild Properties
creditCardNumberObjectYesConfigures the credit card number field on the checkout.


PropertyTypeRequiredDescription
selectorStringYesjQuery selector that identifies the original credit card number input field that will be transformed into a hosted field.
selectorContextElement 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.
alertIfMissingboolean
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.
tokenSelectorString
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.
placeholderString
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.
callbackfunction(card)
An optional function that will be called with a card object after the card is submitted to the server.
changefunction(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.
errorfunction(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.  


creditCardCvv2ObjectRecommendedConfigured the credit card CVV2 field on the checkout.


PropertyTypeRequiredDescription
selectorStringYesjQuery selector that identifies the original credit card CVV2 input field that will be transformed into a hosted field.
selectorContextElement 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.
alertIfMissingboolean
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.
tokenSelectorString
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.
placeholderString
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.
changefunction(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.
errorfunction(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.

callbackfunction(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.


...

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
languagejavascript
themeDJango
// 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 field library will add one of three classes to the underlying input: noCreditCardNumber, invalidCreditCardNumber, validCreditCardNumber

      if (!jQueryHostedFields(this).val() || jQueryHostedFields(this).hasClass("noCreditCardNumber")) {
        // No value in the credit card field
      }
      if (jQueryHostedFields(this).hasClass("invalidCreditCardNumber")) {
        // The value in the credit card field 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");

Is Ionic Framework Supported?

We have tested hosted fields successfully on the following Ionic environment for iOS:

Code Block
languagebash
titleionic info
Ionic:

   Ionic CLI                     : 6.19.1 (/usr/local/lib/node_modules/@ionic/cli)
   Ionic Framework               : @ionic/angular 6.1.9
   @angular-devkit/build-angular : 13.2.6
   @angular-devkit/schematics    : 13.2.6
   @angular/cli                  : 13.2.6
   @ionic/angular-toolkit        : 6.1.0

Capacitor:

   Capacitor CLI      : 3.5.1
   @capacitor/android : not installed
   @capacitor/core    : 3.5.1
   @capacitor/ios     : 3.5.1

Utility:

   cordova-res : not installed globally
   native-run  : 1.6.0

System:

   NodeJS : v16.15.1 (/usr/local/bin/node)
   npm    : 8.11.0
   OS     : macOS Monterey


FAQ

Q: I'm a small merchant, do I have to be PCI 3.0 compliant?

...