NBCheck JavaScript for Authorization Checkbox Documentation

1.0 Introduction to the authorization checkbox feature

To ensure that every Direct Mode transaction is backed by the customer's authorization, merchants must now include code provided by us which will display a checkbox and corresponding agreement language. This language will be included in the Misc. Info of the transaction details to confirm that the transaction was authorized.

The customer will not be able to click the button or link to proceed with the transaction unless the checkbox is checked. Upon checking the box, the merchant will receive a 14-digit ID number, which must be passed along with the customer's IP Address in the Direct Mode request to tie the customer's authorization with that specific transaction. The next section explains on a technical level how to install the checkbox.

1.1 Principles of Operation

The agreement checkbox is an image located on our secure server. The merchant's code will pass at least three parameters when accessing the image: the account, the amount, and the recurring amount if applicable. If there is no recurring fee, set the recurring amount to 0 (zero).

The image will contain the checkbox, the appropriate agreement language, the amount, and the customer's IP. After the box is checked and the transaction is processed, the words shown in the image will be copied to the Misc. Info of the transaction, creating sufficient proof that the check was authorized.

A randomly generated 14-digit ID is used to tie the customer's authorization with the exact transaction that the customer assented to. The ID is stored in assent_key, and is included in both the initial request for the checkbox image and the Direct Mode request itself.

The merchant will need to make sure the 14-digit ID is passed via the assent_key parameter, and that the customer's IP is passed via the cust_ip parameter. PLEASE NOTE: The merchant MUST provide the assent_key and the cust_ip with every check transaction. If they are not provided the transaction will be rejected!

Merchant initiated repeat billing: For repeat billing of the same customer, the assent_key value from the original transaction must be included. The customer must have agreed to repeat/recurring billing at the time of the original transaction. Future repeat billing of transactions that were originally processed before the assent_key feature was introduced will be grandfathered, meaning they will continue to be approved without it. All new ACH transactions require a valid assent_key.

1.1.1 The javascript

The following code must be inserted in the merchant's html, immediately following the <body> tag. It may not be modified.

1.1.2 The image

The following code displays the customer agreement checkbox in an image. The code must be placed in the proper section of the html such that it appears visually adjacent to the submit button or link. It may not be modified, except for the account, amount, and recurring_amount parameters. The optional parameters listed in section 1.2 may be added to the image URL.

1.1.3 The submit button

The following "onClick" must be added to the merchant's button or link that initiates the transaction. It may not be modified.

onClick="if(!confirm_assent(0)) { alert('You must check the agreement box before proceeding with this transaction.'); return false; }"

1.1.4 Integrating with Direct Mode

Most merchants use <input> tags to store and process information collected from the customer, to be eventually passed along to Direct Mode. Merchants are required to add one new <input> tag in the appropriate section of their html code, as follows:

The value of this input tag is automatically updated by the JavaScript provided in section 1.1.1.

Most merchants take the information captured from the customer and store some of it in their own database before formulating a request to Direct Mode. It's the merchant's responsibility to do whatever programming is necessary on their end to ensure that the assent_key and customer's IP Address is passed along from point to point within their system and submitted with their Direct Mode request.

1.2 Optional features

The following are some optional features that can improve the appearance and behavior of the agreement box, and are not required.

1.2.1 Color customization

The bgcolor and fgcolor parameters may be passed to specify the background color and the text color of the agreement box, respectively. To ensure an easily readable agreement box, the colors will default to black on white if the colors provided were too similar. The example given below demonstrates how the parameters can be passed.

1.2.2 Font customization

The following parameters may be passed to specify the font size and font face of the text in the agreement box.

font_size (for example, font_size=9)
The size can be no smaller than 8, or larger than 20.

font_face (for example, font_size=arial)
The face can be arial, cour, times, or verdana. If it is not one of these, it will default to arial.

1.2.3 Amount adjustments

The following javascript functions may be called to get and set the recurring amounts displayed in the agreement box.

get_assent_amount(amt)
set_assent_amount(amt)
get_assent_recurring_amount(amt)
set_assent_recurring_amount(amt)

These functions may be called if the amount in the agreement box needs to be changed after the box has already been displayed. The agreement box will automatically be unchecked if the above functions are called, and the customer will have to check the box again to agree to the new amount. The example below demonstrates the use of these functions.

1.2.4 Cross-selling

The following javascript function may be called to add or remove additional recurring amounts to the agreement box:

toggle_assent_recurring_amount(sequence_number,product_description,amount,checked)

Parameters should be set as follows:

sequence_number - A positive integer determining the order in which items will appear in the agreement box.
product_description - For example: 'a box of widgets'. This may be set to '' to exclude a description.
amount - The cross-sell dollar amount.
checked - True if the line item should be added to the agreement box, false if it should be removed.

Here is the HTML for an example cross-sell checkbox:

<input type=checkbox onClick="toggle_assent_recurring_amount(1, 'widgets', 9.95, checked)"> Cross sell #1: Widgets, $9.95

See the example given in section 1.3 to see how this feature works.

1.2.5 Image Size

The width parameter may optionally be used to specify the width of the image (for example, width=350). If the width parameter is any smaller than 150, the image will default to a width of exactly 150.

1.3 An example

The following example demonstrates a simple order page that uses the agreement checkbox.

Merchant Payment Page Example
Amount: $29.95

Bank Routing Number:

Bank Account Number:

Cross sell #1: Widgets, $9.95
Cross sell #2: Gadgets, $9.95
Cross sell #3: Doodads, $149.00
Below is the assent_key that would be submitted in the Direct Mode request. It's shown here for demonstration purposes:

assent_key:

Normally, the input field should be written as:
<input type=hidden name=assent_key id=assent_key>

<script language="JavaScript"> function get_assent_amount(amt) { var s = document.images.assent_img.src; var a1 = 8 + Math.max( s.indexOf("?amount="), s.indexOf("&amount=")); var p = s.substr(a1); var a2 = s.indexOf("&",a1); if (a2 >= 0) { p = p.substr(0,a2) } return parseFloat(p); } function set_assent_amount(amt) { var s = document.images.assent_img.src; var a1 = 8 + Math.max( s.indexOf("?amount="), s.indexOf("&amount=")); var a2 = s.indexOf("&",a1); var p = s.substr(0,a1) + amt; if (a2 > 0) { p += s.substr(a2); } document.images.assent_img.src = p; confirm_assent(4); } function get_assent_recurring_amount(amt) { var s = document.images.assent_img.src; var a1 = 18 + Math.max( s.indexOf("?recurring_amount="), s.indexOf("&recurring_amount=")); var p = s.substr(a1); var a2 = s.indexOf("&",a1); if (a2 >= 0) { p = p.substr(0,a2) } return parseFloat(p); } function set_assent_recurring_amount(amt) { var s = document.images.assent_img.src; var a1 = 18 + Math.max( s.indexOf("?recurring_amount="), s.indexOf("&recurring_amount=")); var a2 = s.indexOf("&",a1); var p = s.substr(0,a1) + amt; if (a2 > 0) { p += s.substr(a2); } document.images.assent_img.src = p; confirm_assent(4); } function toggle_assent_recurring_amount(seq_no,desc,amt,ckd) { var s; var a1; var a2; var p; if (seq_no < 10) { seq_no = "0"+seq_no; } s = document.images.assent_img.src; a1 = Math.max( s.indexOf("?cs"+seq_no+"="), s.indexOf("&cs"+seq_no+"=")); p = s; if (a1 < 0 && ckd) { p = s + "&cs" + seq_no + "=" + amt; } else if (a1 >= 0) { a1 += 6; a2 = s.indexOf("&",a1); p = s.substr(0,a1); if (ckd) { p += amt }; if (a2 > 0) { p += s.substr(a2); } } s = p; a1 = Math.max( s.indexOf("?cd"+seq_no+"="), s.indexOf("&cd"+seq_no+"=")); if (a1 < 0 && ckd) { p = s + "&cd" + seq_no + "=" + escape(desc); } else if (a1 >= 0) { a1 += 6; a2 = s.indexOf("&",a1); p = s.substr(0,a1); if (ckd) { p += escape(desc); } if (a2 > 0) { p += s.substr(a2); } } document.images.assent_img.src = p; confirm_assent(4); } function confirm_assent(act) { var s = document.images.assent_img.src; var sl = s.lastIndexOf("/") + 1; var p = s.substr(0,sl); var qm = s.indexOf("?"); var x = s.substr(sl,qm-sl)+"-"; var q = s.substr(qm); var ck = x.indexOf("-checked") > 0; var fc = x.indexOf("-focused") > 0; switch(act) {case 0:return ck; case 1:fc=true;break; case 2:fc=false;break; case 3:ck=!ck; break; case 4: ck=false;} x = x.substr(0,x.indexOf("-")); if(ck) { x+="-checked"; } if(fc) { x+="-focused"; } var ak = q.indexOf("assent_key"); var rn = ""; var f = document.getElementById("assent_key"); if (!f) { alert('Webmaster: You must have an assent_key to update.')} if (ak < 0 && ck) { rn="8999999999999"+Math.floor(Math.random()*99999999999999); rn=rn.substr(rn.length-14); q += "&assent_key=" + rn; f.value = rn;

} else if (ak >= 0 && !ck) { q = q.substring(0, ak-1); rn = ""; f.value = rn; } document.images.assent_img.src=p+x+q; } </script>
<b>Merchant Payment Page Example</b> <p> Amount: $29.95<br><br> Bank Routing Number:<br><input name=routing_number><br> Bank Account Number:<br><input name=account_number><br> <p> <img style="border-style:solid;border-color:black;border-width:thin" src="https://secure.nbcheck.com/assent/v1_png?width=400&font_face=arial&font_size=9&account=110006559149&amount=4.95&recurring_amount=29.95&bgcolor=ffffff&fgcolor=000000" name="assent_img" onMouseOver="confirm_assent(1)" onMouseOut="confirm_assent(2)" onClick="confirm_assent(3)"> <p> <input type=button value="Proceed" onClick="if(!confirm_assent(0)) { alert('You must check the agreement box before proceeding with this transaction.'); return false; }"> <input type=button value="Upsell $5" onClick="set_assent_amount(get_assent_amount()+5)"><br><br> <input type=checkbox onClick="toggle_assent_recurring_amount(1,'widgets',9.95,checked)">Cross sell #1: Widgets, $9.95<br> <input type=checkbox onClick="toggle_assent_recurring_amount(2,'a bunch of gadgets', 9.95,checked)">Cross sell #2: Gadgets, $9.95<br> <input type=checkbox onClick="toggle_assent_recurring_amount(3,'a handfull of doodads',149.00,checked)">Cross sell #3: Doodads, $149.00 <p> Below is the assent_key that would be submitted in the Direct Mode request. It's shown here for demonstration purposes:<br><br> assent_key: <input type=text readonly style="background:#e3e3e3" id=assent_key> <br><br>Normally, the input field should be written as: <br> <pre><input type=hidden name=assent_key id=assent_key></pre>