jQuery Library List
ueForm
Designed to tokenize credit card data for transaction processing.
Include Code:
<code java>
<script type="text/javascript" src="https://sandbox.newtekgateway.com/tokenize/jquery.ueform.js"></script>
</code>
Requires:
- jquery.ueform.js Download Here:jquery.ueform.js.zip
- jQuery version 1.7+
- Google CDN:
<code java><script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script></code>
Basic Form
This is the most basic usage of the ueForm plugin. All that is required is jQuery 1.7 or greater, the plugin itself and a basic form. The default names required by the plugin for the tokenization are address, zip, ccnum, cvv2 and expdate.
<code java>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<form>
Address: <input type="text" name="address" />
Zip: <input type="text" name="zip" />
Credit Card Number: <input type="text" name="ccnum" />
cvv2: <input type="text" name="cvv2" />
Exp Date: <input type="text" name="expdate" />
<input type="submit" value="Submit" />
</form>
<script type="text/javascript" src="https://sandbox.newtekgateway.com/tokenize/jquery.ueform.js"></script>
</code>
When this form is submitted the credit card information will be sent to Newtek Gateway and tokenized. The token will be returned and placed inside of the credit card number field and the cvv2 information will be removed from the form. After this has happened PHP Processing of the submission event will continue as normal.
By default the ueForm plugin will be initialized on all form elements.
Non Default Input Names
In this example the address field has been split into two separate fields, the credit card number has been split into four fields and the zip does not have the default name.
<code java>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<form>
Address: <input type="text" name="address_1" />
Address cont.: <input type="text" name="address_2" />
Zip: <input type="text" name="mZip" />
Credit Card Number:
<input type="text" name="cc_num1" />
<input type="text" name="cc_num2" />
<input type="text" name="cc_num3" />
<input type="text" name="cc_num4" />
cvv2: <input type="text" name="cvv2" />
Exp Date: <input type="text" name="expdate" />
<input type="submit" value="Submit" />
</form>
<script type="text/javascript" src="https://sandbox.newtekgateway.com/tokenize/jquery.ueform.js"></script>
</code>
If you have changed the names from the default values expected by the ueForm plugin, then you must reinitialize the plugin with the options that will tell the plugin what fields to use.
<code javascript>
<script>
$('form')
.ueForm({
name_map : {
ccnum : ['cc_num1', 'cc_num2', 'cc_num3', 'cc_num4'],
address : ['address_1', 'address_2'],
zip : 'mZip'
}
});
</script>
</code>
This javascript uses the name_map option parameter to tell the plugin that it should use the inputs with names address_1 and address_2 for address and cc_num1, cc_num2, cc_num3 and cc_num4 for ccnum. If multiple inputs are to be used for a single field then you should use an array of the name values. Single value inputs such as zip in this example do not need to be an array. When the values from a multi field input such as address or ccnum are combined they will have their whitespace trimmed and be concatenated together in order provided with a single space separating each value.
Ajax Submission Through Click Event Without Form
The previous two examples both used the form's submit event to process the form. However, this is not the only way to process form data. Through the use of ajax requests and javascript, forms can be processed using other events such as a button's click event. Notice in the code below that the button input is of type button and not submit. Also in this example the form tag has been replaced with a div.
<code java>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<div>
Address: <input type="text" name="address" />
Zip: <input type="text" name="zip" />
Credit Card Number: <input type="text" name="ccnum" />
cvv2: <input type="text" name="cvv2" />
Exp Date: <input type="text" name="expdate" />
<input type="button" id="ajax-submit" value="Ajax Submission" />
</div>
<script type="text/javascript" src="https://sandbox.newtekgateway.com/tokenize/jquery.ueform.js"></script>
</code>
By default when this button is pressed nothing will happen. However in the code below we use jQuery to bind code to the click event of the button. The code inside of the jquery click event processes the input data and sends the data for processing by use of an ajax call. In order to properly tokenize the credit card data before your click event handler you must initialize the ueForm plugin on the element whos' action will ultimately submit the data. In this instance it is the button with id ajax-submit and we're using the click event. The options we must use are event and container. The values we pass in are click for event because that is the event used to process the input and div for container because it is the element that contains all of the input required. The container option takes a jQuery selector as its value. The ueForm plugin will look for parents of the target, in this case #ajax-submit, which match the selector provided by the container option. Once the container element has been found all descendent input elements will be serialized for processing.
<code java>
<script>
$('#ajax-submit')
.ueForm({
event : 'click',
container : 'div'
})
.click(function(e){
... // Gather data
$.ajax({
... // Make an ajax request to process the data
})
});
</script>
</code>
Alternatively you could add the events like this.
<code java>
<script>
$('#ajax-submit')
.click(function(e){
...
});
$('#ajax-submit')
.ueForm({
event : 'click',
container : 'div'
});
</script>
</code>
I know what you're thinking. "Hold your horses there programming wizard. Javascript events are processed in a first in first out (FIFO) queue. If you add the .click event before .ueForm adds its .click event the tokenization will happen second!" It is true that events on elements are processed in the order they are added, however the ueForm plugin jumps the line and inserts its event as the first event to be executed. Since this is the case you must be sure not to use any code that similarly tries to jump the line in the event queue. If you require such functionality then you must call .ueForm after adding your event.
Javascript Generated HTML
Another possibility for a website is that the form is not HTML on the page but rather html injected by javascript.
<code java>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<div id="dynamic-form-container"></div>
<script>
$('#dynamic-form-container')
.html(
'<form id="dynamic-form">'+
'Address: <input type="text" name="address" placeholder="1833 Victory Bvld"/>'+
'Zip: <input type="text" name="zip" placeholder="91202"/>'+
'Credit Card Number: <input type="text" name="ccnum" placeholder="5555 5555 5555 5555"/>'+
'cvv2: <input type="text" name="cvv2" placeholder="555"/>'+
'Exp Date: <input type="text" name="expdate" placeholder="09/22"/>'+
'<input type="submit" id="ajax-primary" class="btn btn-primary" value="Submit" />'+
'</form>'
);
</script>
<script type="text/javascript" src="https://sandbox.newtekgateway.com/tokenize/jquery.ueform.js"></script>
</code>
Once the form has been created the ueForm plugin must be called on the form.
<code java>
<script>
$('#dynamic-form').ueForm();
</script>
</code>
Token Duration
Tokens may be valid for either a length of time up to 8 hours, 28800 seconds, or for the life of the card they represent. A token by default is only valid for 900 seconds, or 15 minutes. This time may be increased by adding a hidden field with the name duration to the HTML form (The duration value is in seconds). In order for the token to be valid for the life of the card you must initialize the ueForm plugin on the form and set the indefinite option to true.
<code java>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<form>
Address: <input type="text" name="address" />
Zip: <input type="text" name="zip" />
Credit Card Number: <input type="text" name="ccnum" />
cvv2: <input type="text" name="cvv2" />
Exp Date: <input type="text" name="expdate" />
<input type="submit" value="Submit" />
<input type="hidden" name="duration" value="28800" />
</form>
<script type="text/javascript" src="https://sandbox.newtekgateway.com/tokenize/jquery.ueform.js"></script>
</code>
You can also set the duration by setting the duration options parameter when initializing ueForm.
<code java>
<script>
$('form')
.ueForm({
duration : 28800 // 8 hours
});
</script>
</code>
The code below will set tokens generated via this to be valid until the card expires.
<code java>
<script>
$('form')
.ueForm({
indefinite : true
});
</script>
</code>
The indefinite option overrides any set duration.
Error Handling
There are two different error situations that the ueForm plugin can encounter. The first is missing input data required for tokenization or a malformed credit card number. The second is an error thrown by the call to Newtek Gateway when tokenizing the credit card data.
<code java>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<form>
Address: <input type="text" name="avs_street" />
Zip: <input type="text" name="avs_zip" />
Credit Card Number: <input type="text" name="cc_num" />
cvv2: <input type="text" name="cvv2" />
Exp Date: <input type="text" name="exp_date" />
<input type="submit" value="Submit" />
</form>
<script type="text/javascript" src="https://sandbox.newtekgateway.com/tokenize/jquery.ueform.js"></script>
</code>
When malformed or missing data is discovered the form_error function will be called. The parameter errors is an object containing the members address, zip, ccnum, cvv2 and expdate. Each member will be either boolean true, indicating an error with this field or false, indicating no error. When an error occurs during the tokenization of the credit card data the function error will be called. This function gets passed two parameters, the error code and the error text.
<code java>
<script>
$('form')
.ueForm({
form_error : function ( errors ) {
...
},
error : function ( code, text ) {
...
}
});
</script>
</code>
Putting It All Together
All together now! (minus html injection)
<code java>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<div id="all-together-input">
Address: <input type="text" name="address_1" />
Address cont.: <input type="text" name="address_2" />
Zip: <input type="text" name="mZip" />
Credit Card Number: <input type="text" name="cc" />
cvv2: <input type="text" name="cvc" />
Exp Month: <select name="exp_mth" /> ... </select>
Exp Year: <select name="exp_yr" /> ... </select>
<input type="button" id="btn-process-payment" value="Submit" />
</div>
<script>
$('#btn-process-payment')
.ueForm({
event : 'click',
container : '#all-together-input',
duration : 1800, // 30 minutes
name_map : {
address : ['address_1', 'address_2'],
zip : 'zip',
ccnum : 'cc',
ccv : 'cvc',
expdate : ['exp_mth', 'exp_yr']
},
form_error : function ( errors ) {
var error_text = '';
$.each( errors, function( field, isError ){
if ( isError )
error_text += field + ', ';
})
error_text = error_text.slice( 0, -2 ); // Remove the trailing comma and space
alert('Form Error: Incorrect input for ' + error_text + '.');
},
error : function ( code, text ) {
alert('Error (' + code + '): ' + text);
}
})
.click(function(e){
...
});
</script>
<script type="text/javascript" src="https://sandbox.newtekgateway.com/tokenize/jquery.ueform.js"></script>
</code>
Change Log
1.0 Initial commit. 2014/08/28