Table of Contents |
---|
UltraCart Hosted Credit Card Fields
...
Code Block | ||||
---|---|---|---|---|
| ||||
<script type="text/javascript" src="https://securetoken.ultracart.com/js/jquery-1.11.3.min.js"></script> <script type="text/javascript" src="https://securetoken.ultracart.com/js/json3.min.js"></script> <script type="text/javascript"> // Take the version that we just included and scope it locally. The noConflict will return $ and jQuery to their // original values so that the version of jQuery used for the hosted fields does not conflict with any other existing // version of jQuery or other JS library that use $ that are on the page. var jQueryHostedFields = $.noConflict(true); // Also make sure that we're providing consistent JSON functionality in browsers, but don't pollute existing libraries // by running our version in noConflict mode. This will restore whatever is there similar to jQuery. // This will also make sure we have a JSON implementation in older versions of IE. var jsonHostedFields = JSON3.noConflict(); </script> <script type="text/javascript" src="https://securetoken.ultracart.com/checkout/checkout-hosted-fields-1.0.js"></script> <script type="text/javascript">window.UltraCartHostedFields || document.write('<script src="//securetoken.ultracart.com/checkout/checkout-hosted-fields-1.0.js?r=' + new Date().getTime() + '"><\/script>')</script> |
...
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".
| ||||||||||||||||||||||||||||||||
config | object |
|
...
Type | Description |
---|---|
UltraCartHostFields | Instance of the hosted fields object. This variable should be stored way if any of the advanced methods need to be called. |
SessionCredentials
This object contains necessary identifiers that must be passed by the UltraCart Hosted Credit Card Fields to sync up the data properly with the customer's shopping cart session.
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.
|
...
Property | Type | Required | Description | Child Properties | |||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
creditCardNumber | Object | Yes | Configures the credit card number field on the checkout. |
| |||||||||||||||||||||||||||||||||
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 forms. |
cardType | String | The type of card. This value can be used to select a drop box input for perform validation. |
The instance object returned from setup also has some additional methods that can be called.
...
Tip |
---|
Example:
|
The next two methods addClass and removeClass can be used to adjust classes on the iframe's document body. This allows for the CSS of the internal iframe to change state based upon behaviors taking place on the parent document.
...
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
...
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
<script type="text/javascript" src="https://securetoken.ultracart.com/js/jquery-1.11.3.min.js"></script> <script type="text/javascript" src="https://securetoken.ultracart.com/js/json3.min.js"></script> <script type="text/javascript"> // Take the version that we just included and scope it locally. The noConflict will return $ and jQuery to their // original values so that the version of jQuery used for the hosted fields does not conflict with any other existing // version of jQuery or other JS library that use $ that are on the page. var jQueryHostedFields = $.noConflict(true); // Also make sure that we're providing consistent JSON functionality in browsers, but don't pollute existing libraries // by running our version in noConflict mode. This will restore whatever is there similar to jQuery. // This will also make sure we have a JSON implementation in older versions of IE. var jsonHostedFields = JSON3.noConflict(); </script> <script type="text/javascript" src="https://securetoken.ultracart.com/checkout/checkout-hosted-fields-1.0.js"></script> <!-- the following line is a redundant check to ensure the hosted fields file is loaded first --> <script type="text/javascript">window.UltraCartHostedFields || document.write('<script src="//securetoken.ultracart.com/checkout/checkout-hosted-fields-1.0.js?r=' + new Date().getTime() + '"><\/script>')</script> <script type="text/javascript"> jQueryHostedFields(document).ready(function() { UltraCartHostedFields.setup(jQueryHostedFields, jsonHostedFields, { 'sessionCredentials': { 'merchantId': 'DEMO' // Change to your merchant ID // NOTE: This example if for a form post. If you're using a javascript checkout, the session credentials // also need the 'shoppingCartId'. But ONLY for javascript checkouts. }, 'cssUrls':[ // 'https://www.mysite.com/styles.css' ], 'form': '#myForm', // This is only needed for a form POST. javascript checkouts should not be providing this. 'hostedFields':{ 'creditCardNumber': { 'selector': '#cardNumber', 'tokenSelector': '#cardNumberToken' // This is only needed for a form POST. javascript checkouts dont deal with tokens }, 'creditCardCvv2': { 'selector': '#cvv2', 'tokenSelector': '#cvv2Token' // This is only needed for a form POST. javascript checkouts dont deal with tokens } } }); }); </script> <form action="https://secure.ultracart.com/cgi-bin/UCEditor" method="POST" id="myForm"> <!-- Change the value of this input to your merchant ID --> <input type="hidden" name="merchantId" value="DEMO"> <!-- These are the two token values that will be submitted to the UltraCart server that will sync up the sensitive data --> <input type="hidden" name="CreditCardNumberToken" id="cardNumberToken"> <input type="hidden" name="CreditCardCvv2Token" id="cvv2Token"> <input type="text" name="CreditCardNumber" id="cardNumber" value=""/> <br/><br/> <input type="text" name="CreditCardCVV2" id="cvv2"/> <br/><br/> <input type="submit" value="submit"> </form> |
...
The github home page for the responsive checkout has a section with instructions for adding hosted fields to your javascript checkout. It's easy. There's a detailed github gist linked within the instructions that has all the code you should need.
Anchor | ||||
---|---|---|---|---|
|
How do I know if Hosted Fields are even working??
...
Second, do you see a couple of hosted field jsp files loading? One should load for each field (credit card, cvv) to create an iframe for each.
Third, do you see a call going out to UCCheckoutAPIHostedFields each time you enter a full value in either the credit card or cvv field? Was the call successful?
Finally, can you put through test orders? If you're seeing all of the above correctly, and still getting back errors about a missing credit card number, check your UltraCartHostedFields.setup block. That's been the problem the majority of the time. Here are the usual culprits:
...
Code Block | ||||
---|---|---|---|---|
| ||||
// 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(){ // Clear existing 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 invalid var fieldValue = jQueryHostedFields(this).val(); if (fieldValue === "") { jQueryHostedFields("#cardNumber").addClass("noCreditCardNumber"); } else if (re.test(fieldValue)) { jQueryHostedFields("#cardNumber").addClass("validCreditCardNumber"); } else { jQueryHostedFields("#cardNumber").addClass("invalidCreditCardNumber"); } }); 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"); |
FAQ
Q: I'm a small merchant, do I have to be PCI 3.0 compliant?
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<div class="bender-12 columns"> <ul id="card_logos" {{#ucCompare cart.creditCardType 'false' operator="!="}}class="is_{{cart.creditCardType}}"{{/ucCompare}}> <li class="card_visa">Visa</li> <li class="card_mastercard">MasterCard</li> <li class="card_amex">American Express</li> <li class="card_discover">Discover</li> </ul> </div> |
...
Q: I've implemented hosted fields and now the credit card number isn't masked after entering it.
A: That's okay. The card will mask if the number is loaded from the cart or the page is reloaded. By design, it doesn't mask upon entry anymore.