Audience: Implementors of merchants' websites, and I/S service/support staff responsible for helping them.
Prerequisites: Basic understanding of credit card transactions and order entry; experience with HTML and CGI.
This page shows how to construct an HTML form that invokes OMARS to enter a credit card transaction. It has the same capabilities as the OMARS back-office Order Entry service, except the look and feel of the initial HTML form page are entirely under your control. Consider using this technique if all of the following are true for your application:
The customer loads your form page in his/her Web browser, fills in the appropriate inputs, and submits it. The arguments are then sent to the OMARS server in an HTTPS (SSL-encrypted HTTP) "POST" transaction, to invoke the Order Entry service. The OMARS server then produces an HTML page showing the result of your customer's transaction -- either an error page if the inputs were incorrect or the transaction was declined, or a "receipt" page when it is accepted. The content of these pages is controlled by OMARS, although you can adjust the background color to match your pages.
NOTE: Your customers will be concerned that their credit card numbers are appropriately protected. Be sure your order-entry form includes a statement that it is safe and you are looking out for their interests.
However, some users will inevitably worry if they see a non-HTTPS form page asking for their credit card number. Their browser will show a broken lock icon or something to indicate that the page itself is "not secure"; and this is true, it was not encrypted because it has no sensitive data! Unfortunately, the browser will not show that the actual transaction that passes the senstive data, the form tag's ACTION URL, is a secure link.
Alternately, you can just offer the customer some "warm fuzzies" by putting your form page on an HTTPS server. Since this is not easy to do with the IS-provided Web server at http://web.mit.edu/, we are providing an alternate service. It exports your Athena locker (including departmental and project lockers) as a Web site in exactly the same way as the web.mit.edu server, only the pages are all under an HTTPS URL. Our HTTPS server does not require a Personal MIT Certiciate so it can be used by anyone in the world. You still maintain your Web pages in your Athena locker just as you do for pages on http://web.mit.edu/.
To use our server, simply change the beginning of your URL, replacing http://web.mit.edu with https://shopmit.mit.edu . Notice that "http" is replaced by "https" as well as the hostname change. Be sure you use this URL whenever you advertise or link to the form page. Set the ReturnLink CGI argument to the "shopmit" URL as well.
Here is a more detailed discussion of design choices that affect the configuration:
Recommendation: It is best to configure a fixed transaction type (such as PreAuth) at the OMARS level, so your form does not have to worry about it, and so it cannot be subverted, e.g. by a user manipulating hidden CGI argument values.
If you supply your own OrderID, it must be a string value without embedded spaces, no more than 36 characters long.
Recommendation: Let OMARS generate the OrderIDs. You can have OMARS configured with a special prefix to be used on OrderIDs generated from the Order Entry service used by this form, to help sort and identify them. You can also ask for OrderIDs to be prefixed with the category name of the order (see Order Categorization below).
The Order Entry service can be configured to "require" an Order Comments value. If the customer leaves that entry field blank, the order will be rejected with an appropriate message. You may wish to do this if you let the user enter a value for the Order Comments and you want to be sure they enter something.
The contents of the Order Comments field is displayed in the receipt page for a successful transaction. You can configure the label on this receipt line by asking Merchant Services to change it; the default is simply "Order Comments".
Recommendation: Normally, let Order Comments be an optional input. Only make it required if you are letting the user enter the entire value and you want to ensure they do not leave it blank. Have Merchant Services configure the Order Comments label to something meaningful if you are putting anything in the Order Comments field, so the receipt page makes sense.
Your form declares the "class" of the order by supplying a CGI argument (OrderClassified) with the category name. The categories do not have to be pre-configured, although there is a benefit if they are: When the chosen category is configured in the store, it can have a detailed description field added to the order as well. This is helpful when the category is chosen by one input (such as a menu) in your Web form; the Web form is not capable of choosing the appropriate description as well.
The "short" symbolic order classification may be up to 40 characters long. The descriptive phrase may be up to 64 characters. Here is an example of order categories and descriptions for an alumni contribution page:
OrderClassified | Description |
---|---|
picnic | Freshman Picnic |
potholes | Filling Potholes Left by Construction |
pres | President's Discretionary Fund |
Recommendation: Use Order Classifications if you have classes (categories) of orders that you need to separate out later. If you use a small and fixed set of OrderClassified keyword values, then have Merchant Services set up order classification records in your store configuration. Please note that you'll have to make another request keep the store configuration up to date if your classifications change, so don't use this if they change frequently.
Recommendation: Establish a dedicated mailing list to make it easy to change who gets the mail. Include members of the merchants staff who can help customers with questions. They will forward any problems they can't manage to the Merchant Services staff.
Recommendation: If your web form is meant to be used by the general public, then tell Merchant Services to set the access control to "*", which allows everyone. If, however, it is meant for use by a back-office order entry operation and you only want your office staff to have access, have it configured with the appropriate access control list.
Recommendation: For order entry using custom HTML forms, it is usually best to have Merchant Services configure your Order Entry service with receiptIncludeEntryClerk turned off. You can try leaving it on at first and see how you like the appearance of the receipt before making the final decision.
To label an input variable, add another CGI input whose name is "Label-of-" followed by the name of the variable being labelled. Its value is the label. For example, to label the ExpiresMonth input, add this to your HTML:
<INPUT TYPE=HIDDEN NAME="Label-of-ExpiresMonth" VALUE="Credit Card Expiration Month">Now, if the customer fails to make a selection, the warning page generated by OMARS refers to this field as "Credit Card Expiration Month", which is presumably how it is labelled on the custom HTML form. This makes it easier for the customer to understand exactly what he or she got wrong on the form.
If your store is configured for Order Classification (see above), then the following input field is also required:
The inputs that fully describe a billing address are as follows:
(Note that AVS actually only requires the first line of the street address with a street number, and the ZIP code, for US addresses. However, it is usually less confusing to allow the user to enter the entire address, unless your form is only being used by trained back-office data entry operators who don't need to spend any extra time filling out unnecessary fields.)
We recommend seeking out the SELECT (menu input) tags for the BillingCountry, ExpiresMonth , and ExpiresYear inputs, since they are easy to reuse and will save you the trouble of writing the exact same thing.
Using menu inputs for the expiration date fields eliminates is recommended because it eliminates the chance of users entering unacceptable, badly formatted dates (e.g. leaving out the leading 0 on a one-digit number).
Here is an example of an input field for the BillingName, with a 40-character wide input field but a 60-character hard limit (as is required by that argument):
<INPUT TYPE=TEXT NAME="BillingName" SIZE=40 MAXLENGTH=60>
NAME attr. | Req | Len | Description and Purpose |
---|---|---|---|
BillingName | No | 60 | The customer's name as it appears on the credit card. Case is not important, so it does not have to be "all caps". We recommend capturing the billing name whenever possible since it makes transactions easier to identify later. Include instructions on your form that this is to be the name on the credit card, since that is not always the name of the person for whom the payment is being made. |
BillingCompany | No | 40 | The company name as it appears on the credit card, in the case of corporate "purchase cards". |
BillingStreet1 | No | 60 |
The first line (number and street) of the customer's "billing address", that is,
the address
to which credit card statements are mailed.
AVS Note: This field is used in AVS (Address Verification Service), which can get you a better discount rate on the transaction. AVS only looks for a numeric value at the start of this field, assuming it is the street number of the address. AVS does not even try to match street names. So, the address should be entered as e.g. "1 First St.", not "One First St.". |
BillingStreet2 | No | 60 | Second line, if any, of street address in customer's billing address. |
BillingStreet3 | No | 60 | Third line, if any, of street address in customer's billing address. |
BillingCity | No | 25 | The city name in the customer's billing address. |
BillingState | No | 25 | The State or Province name in the customer's billing address. In the US, two-letter state abbreviations are acceptable. |
BillingZip | No | 20 |
The ZIP (US) or equivalent postal code in the customer's billing address.
AVS Note: This field is used in AVS for US addresses (see BillingStreet1). It must be either a 5-digit or 9-digit ZIP code, without any internal punctuation -- just the numerals. |
BillingCountry | No | 3 | The 3-digit ISO country code of the country in the customer's billing address. This is the format required by ClearCommerce. Do not ask the customer to enter a numeric code, but provide a menu of countries to choose from. See the Tips & Tricks section for a suggestion of how to extract the country SELECT tag from an existing OMARS Order Entry page to use in your page. |
BillingCustomerPhone | No | 30 | Voice telephone number given by the customer as a contact. There are no restrictions on the format, as it is not used by ClearCommerce. |
BillingCustomerFax | No | 30 | FAX telephone number given by the customer as a contact. There are no restrictions on the format, as it is not used by ClearCommerce. |
Cardnumber | Yes | 40 | Credit card (account) number. May include spaces or dashes. Maximum size of 40 characters, although the input field on the form only needs 19 characters to accomodate the typical format of 4 groups of 4 digits with a space or dash separating each, e.g. 4242-4242-4242-4242. |
ChargeAmount | Yes | 20 |
Amount of money to be charged for goods and services. This is
a subtotal when either of the
TaxAmount or
ShippingAmount inputs
have values. When they are left out, which is most of the time,
ChargeAmount is effectively the total to be charged.
The value must be a decimal dollar amount without the dollar sign or any punctuation other than the decimal point, e.g. 2.50. Note: You do not need to break out tax and shipping charges into separate inputs -- that only lets ClearCommerce keep track of them separately. It is allowable to add them together into this one input. |
CustomerEmail | No | 64 |
The customer's email address. This input should only be considered
required if your ClearCommerce store is configured to send digital
receipts (email confirmations) to the customer, since they are
sent to this address. Otherwise this input can be considered
optional. The value must include an "@" character
even for local MIT addresses.
Note that even when digital receipts are in use, the Order Entry service does not consider this a required input. It will accept orders without this input, although of course they will not get a digital receipt. |
Cvm | No | 4 | Credit card CVM (Card Verification Method) code. This is a 3 or 4-digit number imprinted on the physical credit card, but not embedded or encrypted in the magnetic stripe. It helps validate that the customer is in possession of the credit card, and may get you a better discount rate on the transaction. If the input is supplied, it must be a 3- or 4-digit decimal number. |
ExpiresMonth | Yes | 2 | The month in which the credit card expires. It must be expressed as a two-digit number with leading zero, e.g. "01" - "12". Since the format is so restricted, we recommend you use a menu selection such as the SELECT tag for this input. See Tips & Tricks. |
ExpiresYear | Yes | 2 | The year in which the credit card expires. It must be expressed as a two-digit number with leading zero, e.g. "03". Since the format is so restricted, we recommend you use a menu selection such as the SELECT tag for this input. See Tips & Tricks. |
EntryClerk | No | 32 |
Usually, this indicates who was responsible for entering this order;
for orders entered by a merchant's back-office staff, it usually identifies the operator
who submitted the Web form.
For orders submitted from a Web page open
to the general public, there is no authenticated user,
so there isn't anything obvious to use for a value.
You can use this input to store any piece of useful data with the order, such as a customer identification number or invoice number. You will be able to see it in OMARS reports. It will also be shown in the receipt page unless the configuration parameter receiptIncludeEntryClerk is off. |
OrderClassified | No | 40 | Symbolic identifier of the order category, e.g. "Lab Fee". May be up to 40 characters long. Use this when you need to classify the orders into a few different categories; e.g. have the user select the category from a menu in your form. This should be one of a small set of keywords so you can use the OMARS Category Report to list orders by category. |
OrderComments | Maybe | 64 | This is a required input only the Order Entry service is configured to make it required; otherwise it is optional. The value can contain anything; it is just a string that ClearCommerce keeps associated with this order. You can use it to store a reference to other data records related to the order. |
OrderID | Maybe | 36 |
This input is either required or forbidden, depending on how
the Order Entry service is configured. If it was set up to generate OrderIDs
automatically, you must not supply this input. Otherwise, you must
supply a value which is unique identifier for the new order to be created.
We strongly recommend using OMARS' automatically-generated OrderIDs. If you want to relate the order to an invoice number or other external identifier, put that identifier in the OrderComments input -- so, if the customer fails to provide that identifier or makes a mistake, the order can still be processed. There are exceptions: If you are driving this form from a CGI script that has a source of guaranteed unique identifiers, and you need to know the OrderID of the created order, that is a good case for using this input. |
ReturnLink | No | n/a | The absolute URL of the page to "return" to after finishing this payment form: it can be the URL of the payment form itself, or the URL of a page that leads to it. This link is displayed (labelled with the text in ReturnLinkLabel) on the receipt and error pages generated by the Order Entry service. You will probably want to express this as an input with the type HIDDEN so it is not a visible part of the form. |
ReturnLinkLabel | No | n/a | This supplies the text to show over the ReturnLink link. Pick a phrase that makes sense after the words "Return to", e.g. "The Virtual Shark-tank". This phrase is displayed after the words "Return to" on the receipt and error pages generated by the Order Entry service. You will probably want to express this as an input with the type HIDDEN so it is not a visible part of the form. |
ShippingAmount | No | 20 |
A separate dollar amount to be charged for shipping. It is
added to the ChargeAmount and
TaxAmount inputs (see above) to
make the total amount of the transaction.
It must be a decimal dollar amount without
any additional punctuation, e.g. "13.45".
Note that this is only needed if you want to track shipping charges separately in ClearCommerce. Most merchants do not use it. |
ShippingName | No | 60 |
The customer's "ship-to" address, ostensibly for delivery of goods.
Each of these fields has the same purpose, limitations, and semantics
as the similarly-named field in the Billing Address.
Most merchants do not need these inputs. You should only supply them if you want ClearCommerce to keep track of a second, alternate, customer name and/or address for each order. The shipping address is not needed for anything within ClearCommerce, it just passes through the system. The shipping address fields are displayed in the detailed order view in OMARS Order Management. See also: UseBillingForShipping input. |
ShippingCompany | No | 40 | |
ShippingStreet1 | No | 60 | |
ShippingStreet2 | No | 60 | |
ShippingStreet3 | No | 60 | |
ShippingCity | No | 25 | |
ShippingState | No | 25 | |
ShippingZip | No | 20 | |
ShippingCountry | No | 3 | |
ShippingCustomerPhone | No | 30 | |
ShippingCustomerFax | No | 30 | |
TaxAmount | No | 20 |
A separate dollar amount to be charged for state tax. It is
added to the ChargeAmount and
ShippingAmount inputs
to make the total amount of the transaction.
It must be a decimal dollar amount without
any additional punctuation, e.g. "1.05".
Note that this is only needed if (a) your store collects state tax (most MIT merchants do not), and (b) you want to track tax charges separately in ClearCommece. Most MIT merchants do not need this input. |
TransactionType | Maybe | n/a |
This is ONLY needed when your store is not configured
with a fixed transaction type. Most merchants can ignore it.
The value must be one of the keywords: PreAuth or Auth. Any other value results in an error every time the form is submitted. |
UseBillingForShipping | No | n/a |
This input tells the Order Entry service to copy the billing address
fields into the shipping address.
The value must be "checked" or empty.
Use this input when your form has a separate shipping address and you want to offer the customer the option of also using the billing address for shipping instead of typing it all over again. |
Label-of-Name | No | n/a |
An input whose name begins with Label-of-
defines a user-friendly label for one of the inputs to the
Order Entry service. Name is one of the input names defined
in this table.
The label is used to identify the field in error pages describing missing or illegal inputs. Using a label that matches the labelling of the input in your HTML form can help the user identify what he/she got wrong. See the section on labels for more details and an example. |
do not use this if the form is a static page, since it is not a good idea to ask users to come up with unique order IDs.
Example: (newlines added for clarity)
<!-- Adds tear-off second copy of receipt to receipt pg. (for merchant records) --> <br><br><hr><i>Merchant Copy:</i><br> <script> tbls = document.getElementsByTagName("table"); document.write('<table align="center" cellspacing="3" cellpadding="2" border="0" width="80%">'); document.write(tbls[0].innerHTML); document.write("</table>"); </script> <p></p><br><b>Customer Signature: ________________________________<hr>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML><HEAD><TITLE>Payment Example Page</TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF"> <H1 ALIGN=CENTER>Payment Example Page</H1> <FORM ACTION="https://omars.mit.edu/payment/mystore_form" METHOD=POST> <INPUT TYPE="HIDDEN" NAME="ReturnLink" VALUE="http://web.mit.edu/mylocker/www/mypay.html"> <INPUT TYPE="HIDDEN" NAME="ReturnLinkLabel" VALUE="My Payment Form"> <B>Name (on your credit card):</B> <INPUT NAME="BillingName" TYPE=text SIZE=45 MAXLENGTH=60> <P> <B>Account Number:</B> <INPUT NAME="Cardnumber" TYPE=TEXT SIZE=19 MAXLENGTH=40> <I>(accept only MasterCard, Visa, & AmEx)</I> <BR><B>Expiration Date:</B> <SELECT NAME="ExpiresMonth" > <OPTION VALUE="" SELECTED>--Month-- <OPTION VALUE="01">January (01) <OPTION VALUE="02">February (02) <OPTION VALUE="03">March (03) <OPTION VALUE="04">April (04) <OPTION VALUE="05">May (05) <OPTION VALUE="06">June (06) <OPTION VALUE="07">July (07) <OPTION VALUE="08">August (08) <OPTION VALUE="09">September (09) <OPTION VALUE="10">October (10) <OPTION VALUE="11">November (11) <OPTION VALUE="12">December (12) </SELECT> / <SELECT NAME="ExpiresYear"> <OPTION VALUE="" SELECTED>--Year-- <OPTION VALUE="02">2002 <OPTION VALUE="03">2003 <OPTION VALUE="04">2004 <OPTION VALUE="05">2005 <OPTION VALUE="06">2006 <OPTION VALUE="07">2007 <OPTION VALUE="08">2008 <OPTION VALUE="09">2009 <OPTION VALUE="10">2010 <OPTION VALUE="11">2011 <OPTION VALUE="12">2012 <OPTION VALUE="13">2013 </SELECT> <BR><B>Amount to pay:</B> <TT>$</TT> <INPUT NAME="ChargeAmount" TYPE=TEXT SIZE=20> <P><INPUT TYPE=RESET name="Reset" VALUE="Clear Form"> <INPUT TYPE=SUBMIT VALUE="Submit Payment"> </FORM> <HR><FONT SIZE=-1>Please direct comments or questions to the store administrator, at <a href="mailto:devnull@mit.edu"><devnull@mit.edu></a>.</font> </BODY></HTML>Here is a more extensive example, with comments.