OMARS Merchant Setup Questionnaire
Creating a New Store

lcs, October 2003

This form collects the data from a merchant needed to configure OMARS for a new store, or to add new services to an existing one. It is meant to be filled out by one of our Merchant Services specialists while interviewing the merchant's staff to acertain their needs.

Shortcuts to Services:

Instructions: Please be sure to fill in all form items marked "Required". The ones marked "Required for service" only have to be filled out if your store is using that service.
If your store does not need a service at all, leave its inputs blank.

General Questions: For all services

These answers are needed to configure any of the services:
  1. Store's Full Name:  Required
    A brief but descriptive phrase naming the merchant, such as "Document Services" or "Mass Tool & Die". This name appears in the title of each OMARS page to identify the merchant.

  2. Store Abbreviation (short name):  Required
    A one-word abbreviated name for the store, such as "docs" or "mtd". It may not contain spaces, though "-" and "_" are allowed. We recommend using an obvious abbrevation of your organization's name.

    This name is used in the URLS of your OMARS web pages, and it identifies your OMARS store to the Merchant Services staff.

    Ticket Number (from ChargeMIT Tracking): (Just the number, e.g. 66)
    Please enter the number of the "ticket" in ChargeMIT's tracking system that covers the creation of your store. This helps us serve you more efficiently. Leave this space blank if you do not have the ticket number.

  3. ClearCommerce Entity Number:  Required
    The entity number of this merchant's store in ClearCommerce. See the Production CSP Entity Map to find it if you do not know. Enter "unknown" if the ClearCommerce store has not been created yet.

  4. Ending Date for Store: ..or.. Ongoing   Required
    Enter the closing date for your store in the format MM/DD/YYYY, or, if you are not planning to close the store, check the Ongoing box. This is the same as the "Ending Date" you entered on the E-Commerce Merchant Registration Form in the "Estimated Period of Activity" section (question 6).

  5. Merchant Email contacts:
    We need to know how to contact the merchant's staff by email for various purposes. Please enter the most appropriate mailbox (i.e. email address) for each class of messages below.

    Consider using MIT-hosted mailing lists for each category -- this lets you change who receives the mail instantly and whenever you want. You can then keep up with changes in staff or their responsibilities. If there is no suitable, existing, list, then use this I/S mailing list form to request a new mailing list now, and enter its name below. You can then administer the list through a Web form too.

    Please give a single fully-qualified email address, such as SpamMe@aol.com, for each purpose. If you want the mail to go to multiple people, create a mailing list.

    1. Automatically-generated Messages:  Required
      If you choose to get merchant copies of "digital receipts" (transaction emails) from the credit card processor, they are sent to this mailbox. It also receives ShopSite merchant notifications if you have a ShopSite store.
      We recommend using a separate mailing list for this purpose, so the recipients can sort it easily. It can produce a high volume of mail.

    2. "Questions and Comments" contact:  Required
      This mailbox will be displayed on the OMARS pages as the contact for comments and questions about the service. It should be someone (or, preferably, a mailing list of several people) on the merchant's staff who can help other users with questions and decide what problems to forward to the OMARS administrator.

    3. Merchant Administrative/Technical Contact:  Required
      This is the person (or, preferably, mailing list of people) whom we will contact if there are any problems with your store. They should be part of the merchant's staff, and knowledgeable about the e-commerce system. We recommend using a list with several members so there is coverage over individual staff absences. We will also use this contact to notify you of new features and changes in the e-commerce services.

  6. Background color: (Optional)
    Specify the background color of your OMARS pages, to distinguish them from other stores you might be managing or other Web pages. The format is a Web color spec, e.g. #ffffff. Use a very pale color since it has to contrast well with the black, blue, and red foreground text colors. Choose a color from this web-safe color chart.

  7. Default ("read") Access list:
    Default list of people who are allowed to use OMARS services. Each service can its own access-control list, but it will also let you refer to this default list to save repetitive typing. We recommend you use this default list to name the people with "read access" so you can use it for all the reporting services. If your store gives all of the staff complete access, you can use the default list everywhere.

    Enter the Kerberos name of each person to have access, separated by a space and/or a comma from the next name. A person's Kerberos login name is the same as their email address before the "@mit.edu" part. E.g. the Kerberos name of someone who gets mail at florey@mit.edu would be florey. You would enter florey on the list.

    Example: florey, tetazoo, jrandom

  8. Default Order Comments Label:
    The Order Comments Label is used by several services; e.g. to name columns in reports, on order-entry pages and receipts, etc. If you plan to use the same label for all of them, enter it here and choose the default later so you can avoid typos.

    Example: Invoice Number

Point-of-Sale (and/or Back-Office) Order Entry

This service lets the merchant's back-office staff enter orders on a form automatically generated by OMARS. It is designed to be used in either the back office or at a point-of-sale location (with a magnetic stripe reader). Please see the custom HTML page section below if you prefer to use your own custom form page. Your store can still have this service configured in addition to custom form pages.
  1. Use Default Access List: (leave next field empty if checked)
    Access list:  Required for service
    Kerberos names the people who are allowed to use this order-entry form.
    The login name of the actual user who entered the order is recorded with each order, as the "entry clerk".

  2. Transaction Type:
    What sort of transaction is created by this form? The choice is between PreAuth and Auth. PreAuth creates an "unfulfilled" order which must later be fulfilled in the Order Management service. Auth creates an order which already has the funds captured. Be sure you understand the implications of this choice under the rules for credit card transactions.

    There are two configuration options you must choose:

    1. Give the operator a choice of transaction type?  Required for service
      ("No" means the transaction type is fixed; specify the type to use below.)
    2. Which Transaction Type?  Required for service
      This becomes the default if you answered "Yes" to part (a), or the fixed transaction type if you answered "No".

      (Note: Giving operators a choice with a default is more convenient for them, but allows errors if they neglect to make a choice. If you need to protect operators from this pitfall, choose "No Default" here to force operators to make a choice each time.)

  3. Include Verbal Authorization Fields:
    Includes fields in your Order Entry page to let you enter an order for which you have received a Verbal (telephone) Authorization. See Entering Orders with Verbal Authorizations for more information about when you need to do this and how it is done.

    Answer "Yes" if there is any chance you will use this feature. The only cost is a little more clutter on the Order Entry page.

  4. Order Classification:  Required for service
    Do you want to record a "category" for each order, chosen from one of a fixed set? With categories, ClearCommerce can generate reports showing how much money was charged to each category over a time span. The categories are part of the OMARS configuration, so only the server administrator can make changes. Infrequent changes to the category list are not a problem, but daily or weekly changes would be.

    NOTE: If you want control of your own category list so you can make changes frequently, the Order Entry on a Custom HTML Page service may be more appropriate to your needs.

    You need to assign a name to each category, and a longer descriptive phrase. The name must be short (preferably one word or abbreviation). It will appear on Category Reports. The description will appear on the category menu in the Order Entry form, so it is what your operators will actually see.

    For each category, list the symbolic name, followed by a colon (:) separator and the description, one category per line. Example:
    DisFund : My Discretionary Fund.

    Default Category: (Optional)
    Do you want the category choice pre-set to a default? If not, the operator will be forced to actively choose one of the options, which may be preferable depending on your policy. This must be either left blank or set to one of the symbolic names defined above.

  5. Order ID Source:  Required for service
    The OrderId is a unique string that identifies the order created by this form within ClearCommerce. You can let the system assign a unique identifier automatically, or you can choose to assign your own.

    NOTE: Usually, it is preferable to let OMARS make up OrderIDs. Since they must be unique, it is easy to get into trouble:

    • When an order is declined, you cannot re-try the authorization with the same order ID but you must pick a new one. If you depend on orderIDs matching e.g. an invoice number, this breaks that model.
    • If you make a typo on the OrderID, you may accidentally "use up" an identifier needed in the future, or duplicate an existing order. The former will cause trouble later, the latter will simply fail.

    There are better ways to "relate" an OMARS order to some external data such as an invoice or order. Use the Order Comments field (see question 14 below) to hold the reference information, instead of trying to encode it in the order ID. This ensures it will always be exactly what you want.

    If you need to encode some extra information in the OrderID, use the OrderID prefix to do this (see next question).

    Although we strongly recommend using automated OrderIDs, we do allow them to be entered manually. An order ID must be no more than 36 characters long and should not contain spaces.

  6. Order ID Prefix: (Optional; fixed string or %category%)
    This only applies to automatically-generated order IDs. Set this to a short word without spaces. Orders created by this service will start with prefix-. Set this to a meaningful value to distinguish orders entered in this form from those entered in a custom form or some other means.

    If you are using Order Classification (see above), you can set the prefix to, literally, %category% to use the short category name of each order as its individual order ID prefix. This further distinguishes orders entered from this service.

  7. Order Comments:  Required for service
    Each order also has a 64-character field available for an arbitrary data string that travels with the order. Indicate here if you want the Order Entry form to include a field for the Order Comments value; there are options below to add a custom label and instructions to the field. The "Required" choice means the order is not accepted unless some non-blank value is entered for Order Comments. Choose this to ensure the operator does not ignore it.

    You can put anything you like in the Order Comments field, although it is usually best to give it a consistent purpose for all of your orders. It can hold an identifier that points to an entry related to this order in another record-keeping system, e.g. an invoice or billing number. If your store is self-contained you could use it to store some extra information, such as the name of the person on whose behalf the payment was made.

    NOTE: It is also possible to configure the Order Entry form with some validation code (in JavaScript) to test the value supplied for Order Comments, and issue an alert if it is not legal. Since this involves special attention and possibly extra costs, you should contact Merchant Services separately to ask about adding validation if you are interested in adding it.
    Use Default Order Comments Label:
    Order Comments Label:
    Order Comments Instructions:

  8. Credit Cards accepted:  Required for service
    Specify a list of the credit cards your merchant accepts to help operators verify they are entering an acceptible card. The list is shown verbatim with the card number entry box on the order form, as a reminder to the operator. It does not actually affect operation.
    Example: accept only: MasterCard, Visa, Amex.

  9. Magnetic Stripe:
    Do you want the form to include an input box for entering the magnetic stripe of a credit card? Merchants who accept physical credit cards from customers can use this, in conjunction with a correctly-configured ID TECH MiniMag card reader, to fill out the form automatically with the data on the card.

  10. Shipping Address:
    The order entry form always includes a billing address, because it is used to help authenticate the credit card owner and get a better discount rate from the processor. This option allows you to include a shipping address as well. It is not used for anything inside ClearCommerce (although ClearCommerce has a shipping calculator which might be made available to merchants if there is demand for it). You will be able to see the shipping address in the Order Management detailed view.

    Alternate Label for Ship Addr: (Optional)
    Indicate here if you want the entry fields for the shipping address to have a different label on your Order Entry form. Use this to remind the operator when you are using it to collect something other than the "shipping" address. Example: Name and Address of Actual Donor (for contribution website).

  11. Tax line item:
    This adds a separate line item for the amount of tax on your order form. ClearCommerce can use this data to produce reports of how much state tax was collected over time. The tax amount is also shown in the order management views. If your enterprise does not need to charge state tax (as is the case for most MIT merchants), do not enable this option.

  12. Shipping line item:
    This adds a separate line item for the shipping charge to your order. The shipping amount is shown in Order Management detail views.

  13. Exclude EntryClerk from receipt: Check here to exclude the Entry Clerk value from the generated receipt page. The Entry Clerk identifies the authorized user who entered the order; Some merchants prefer not to give this information to customers on a printed receipt page.

Order Entry with Custom HTML Page

This service lets you create your own order-entry HTML page. See OMARS Order Entry from Custom HTML Forms for more details.
  1. URL of your page:  Required for service

    What is the URL of your HTML page? Make up a location even if your page does not exist yet. We recommend using an Athena Locker for your website so you can edit and upload the page easily, and host it through our secure "shopmit" server. To do that, simply construct a URL:
    https://shopmit.mit.edu/lockername/path-under-locker
    e.g.
    https://shopmit.mit.edu/warez/www/p1r4te-mp3s.html

  2. Access: -- who is allowed to enter orders on this page.  Required for service
    Use Default Access List: (leave next field empty if checked)
    Access: Enter "*" to allow Public Access

    This restricts the people who are allowed to enter orders through this form. If you are using the form for your own merchant staff, it makes sense to limit access to them. However, if it is intended for the public at large (i.e. an e-commerce page), enter "*" in the access field.

  3. Transaction Type:  Required for service
    Choose the type of transaction to be entered by your form. This can be left to the discretion of the form itself, but it is better to configure a fixed transaction type to prevent errors, especially with a form that is to be open to the public (e.g. for ecommerce).

  4. Order Classification: Does your form supply the OrderClassified input? If you are using a relatively fixed, unchanging set of categories (values for the symbolic name), then you can configure a table of descriptions for those categories. These descriptions appear in the Order Management views and Category Report. Only OrderClassified values matching a category defined in this table will have a description attached; there is no default.

    For each category, list the symbolic name, followed by a colon (:) separator and the description, one category per line. Example:
    DisFund : My Discretionary Fund.

  5. Order ID Prefix: (Optional; fixed string or %category%)
    Changes the prefix applied to the automatically-generated order IDs of orders entered by this service. Set this to a short word without spaces. OrderIDs created by this service will start with prefix-. Choose a meaningful value to distinguish orders entered in this form from those entered in a back-office form or some other means.

    If you are using Order Classification -- that is, if your form supplies the OrderClassified input -- you can set the prefix to, literally, %category% to use the category name of each order as its individual order ID prefix. This further distinguishes orders entered from this service.

  6. Order Comments Required:
    Do you want your form to "require" that some value be entered for the OrderComments input? Choosing "yes" here configures the OMARS service to reject any orders with an empty OrderComments value, so it forces the user to enter something.

    Use Default Order Comments Label:
    Order Comments Label:
    Specify the label to apply to the Order Comments field on the receipt page generated by OMARS. Only needed if you offer an input for OrderComments.

  7. Exclude EntryClerk from receipt: Check here to exclude the EntryClerk value from the generated receipt page.

  8. Background color: (Optional)
    Specify a custom background color of the generated receipt page, so it matches your custom HTML page. The format is a Web color spec, e.g. #ffffff. Default is the same color as your OMARS store background, which is why you may want to give this service a different background.
NOTE: It is also possible to specify a custom HTML "addendum" to be appended to the Receipt page generated after a successful order. This must be processed separately by the ChargeMIT team, so send mail to chargemit-help@mit.edu if you wish to take advantage of this feature.

ShopSite Gateway

This service is only needed if the merchant is doing business through a ShopSite store.

For more information, see Configuring and Using the ShopSite Gateway.

  1. ShopSite Store: (i.e. login name)  Required for service
    The name of the ShopSite store connected to the ShopSite gateway service. This is the name you enter along with the password when "logging in" to the ShopSite administrative interface.

  2. ShopSite Payment Password:  Required for service
    The password that you set in your ShopSite store's Payment Gateway configuration. It is only used when billing orders, not in the initial authorization. It has no relationship to the ClearCommerce or ShopSite login password. Make up something random and cryptic so it isn't obvious. It protects your ShopSite gateway from being accessed by unauthorized users.

    Record this value or enter it now into your ShopSite store's payment configuration.

  3. URL of ShopSite Store:  Required for service

    The top-level URL of your ShopSite store. It is needed so the Merchant Services staff can find your store for troubleshooting.

  4. SS 5.0 Authorization Transaction Type:  Only required for ShopSite 5.0
    NOTE: DO NOT set this if you are using ShopSite 6.3. The initial transaction type is set in the SS Commerce Setup page in 6.3.
    This lets you choose whether to use a special feature of the ShopSite Gateway to simplify administration of your store. If you are selling intangible goods (e.g. conference or reunion registration), then you can process the orders as "Auth" transactions to capture the funds immediately, instead of the default "PreAuth" where the order is captured (i.e. "billed" or "fulfilled") later.

    If you choose Auth, the ShopSite Gateway will interpret ShopSite's PreAuth requests as Auth transactions, so you'll never need to "bill" them in ShopSite's administrative interface. This saves time for the merchant, and ensures the funds are captured promptly.

    Important: Before choosing Auth, be sure your sales transactions are the kind that allow you to collect funds immediately.

  5. Order ID Prefix: (Optional)
    Changes the prefix applied to the automatically-generated order IDs of orders entered by this service. Set this to a short word without spaces. OrderIDs created by this service will start with prefix-. Choose a meaningful value to distinguish orders entered in this form from those entered in a back-office form or some other means.

    Note that this service does not allow setting the prefix to %category%, since there is no order classification.

Order Management

The Order Management service only requires one choice aside from the common ones:
  1. Access lists: These lists enumerate the people who are allowed to use each Order Management function. People are identified by their Kerberos login name, which is the same as their email address without the "@mit.edu" part. E.g. the login name of someone who gets mail at florey@mit.edu would be florey. The functions are:

    Use Default Access List (only for Read): (leave next field empty if checked)
    Read:  Required for service
    Examine lists of orders and the details of each order. Read access is also a prerequisite for using the other features of Order Management.

    Fulfill:  Required for service
    Fulfill takes a transaction that was created in the PreAuth state and executes a PostAuth to capture some or all of the authorized amount. (Not needed by merchants who only process Auth transactions.)

    Void:  Required for service
    Cancel an order which has not been settled yet, i.e. unfulfilled orders and Auth or fulfilled orders entered on the same day. Once an order has been settled, a Credit transaction is the only way to reverse it.

    Credit:  Required for service
    Credit returns money to the customer. We recommend that merchants only grant Credit permission to the fewest possible staff members.

    Warning: If you are an ASA-recognized Student Group registering through the SAFO, enter only "laurie" here. Only the SAFO officer, Laurie Ward, is allowed to give credits in Student Activity stores.

Transaction Report

The Transaction Report service offers these choices aside from the common ones:
  1. Use Default Access List: (leave next field empty if checked)
    Access:
    Names the people who are allowed to use the transaction report. The people are identified by their Kerberos login name, which is the same as their email address "@mit.edu". E.g. the login name of someone who gets mail at florey@mit.edu would be florey.

  2. Use Default Order Comment Label: (leave next field empty if checked)
    Order Comment Label: (Optional)
    This lets the merchant customize the column containing the "comment" field from the order related to the transaction. If they use the comment for a specific value such as a batch number, it can be labelled "Batch" as a reminder to everyone using the report.

  3. Default Column Selection: Each column in the Transaction Report can be configured to be selected "on" or "off" by default. The merchant should review the available columns (e.g. by experimenting with the demo store) and decide which ones he/she wants enabled by default. This saves time and errors when filling out the form to create a report.

    Note: The columns marked with "(*)" will take extra time when gathering the data for this report.

    Transaction ID Date Entry Clerk (*) Billing Name (*) Ship-to Name (*) Authorized Amount Captured Amount Settled Amount Collected Amount Status Span Order ID (*) Order Comments (*)

Settlement Report

The Settlement Report service offers these choices aside from the common ones:
  1. Use Default Access List: (leave next field empty if checked)
    Access:
    Names the people who are allowed to use the settlement report. The people are identified by their Kerberos login name, which is the same as their email address "@mit.edu". E.g. the login name of someone who gets mail at florey@mit.edu would be florey.

  2. Use Default Order Comment Label: (leave next field empty if checked)
    Order Comment Label: (Optional)
    This lets the merchant customize the column containing the "comment" field from the order related to the transaction. If they use the comment for a specific value such as a batch number, it can be labelled "Batch" as a reminder to everyone using the report.

  3. Default Column Selection: Each column in the Settlement Report can be configured to be selected "on" or "off" by default. The merchant should review the available columns (e.g. by experimenting with the demo store) and decide which ones he/she wants enabled by default. This saves time and errors when filling out the form to create a report.

    Note: The columns marked with "(*)" will take extra time when gathering the data for this report.

    Transaction ID Date Settled Date Entry Clerk (*) Billing Name (*) Ship-to Name (*) Settled Amount Status Span Order ID (*) Order Comments (*)

Category Report

The Category Report service offers these choices aside from the common ones:
  1. Use Default Access List: (leave next field empty if checked)
    Access:
    Names the people who are allowed to use the category report. The people are identified by their Kerberos login name, which is the same as their email address "@mit.edu". E.g. the login name of someone who gets mail at florey@mit.edu would be florey.

  2. Default Column Selection: Each column in the Category Report can be configured to be selected "on" or "off" by default. The merchant should review the available columns (e.g. by experimenting with the demo store) and decide which ones he/she wants enabled by default. This saves time and errors when filling out the form to create a report.

    Date Entry Clerk Billing Name Amount Order ID

Graph Report

The Graph Report produces bar and pie charts of your store's activity over time. These provide a rough qualitative view of "net sales" (captured payments minus credits).

New merchants should try this report with the default settings and keep in mind that the size and bar colors can be adjusted if necessary.

    Use Default Access List: (leave next field empty if checked)
    Access:
    Names the people who are allowed to use the graph report. The people are identified by their Kerberos login name, which is the same as their email address "@mit.edu". E.g. the login name of someone who gets mail at florey@mit.edu would be florey.

  1. Size of graph image (Optional, default is 800x600)
    Height: x Width:

  2. Primary Bar Color: (Optional, in hexadecimal RGB format)
    Color to use in the bar charts showing "Total" amounts; charts of category breakdowns color each category from a predetermined list.

    In the bar chart comparing sales to the previous year, this color is used for the latest year, and the Secondary Bar color (below) is used for the year before that. Choose a color that contrasts well with the white graph background and is distinct from the secondary color.

    The color must be described as 6 hexadecimal digits, in the format rrggbb. The first two digits are the red value (00-FF), the next two are green, and the last blue. This is the color format of the Java AWT (abstract window toolkit) package, and it is similar to the HTML format. Example: ffff00 is bright yellow.

  3. Secondary Bar Color: (Optional, in hexadecimal RGB format)
    Color to use for the lighter bars in some Graph Report bar charts. This is only used by the "Bar Chart of Total Sales, Compare to Previous Year's Totals" graph. It is the color of sales on the previous year, while the Primary Bar Color above colors the bars for the later year. Choose a color that contrasts well with the white graph background and is distinct from the primary color.

    The format is the same as Primary Bar Color above, six hexadecimal digits rrggbb.

Billing & Shipping Address Report

This report lets merchants download name and address information for their orders, for importing into a database or spreadsheet. It is only needed if you are using OMARS to record the names and addresses of your customers, rathern than some external record-keeping system.

    Use Default Access List: (leave next field empty if checked)
    Access:
    Names the people who are allowed to use the category report. The people are identified by their Kerberos login name, which is the same as their email address "@mit.edu". E.g. the login name of someone who gets mail at florey@mit.edu would be florey.

  1. Default Column Selection: Each column in the Address Report can be configured to be selected "on" or "off" by default. The merchant should review the available columns (e.g. by experimenting with the demo store) and decide which ones he/she wants enabled by default. This saves time and errors when filling out the form to create a report.

    Billing Name & Address Ship-to Name & Address

OMARS Order Entry API

This is for merchants using the Java-based Order Entry API.
  1. Client Certificate Name:  Required for service
    The merchant must acquire (from us) a special client certificate -- like a personal Web Certificate but specially constructed for the API. Typically the subject name is "storename.omars", e.g. cao.omars. Fill this out even if you haven't got the certificate yet, since it provides the name to put on the cert.

  2. OrderID Prefix:
    If the API client does not supply an OrderID, OMARS generates one automatically. You can supply a prefix to start the identifier. It should be a short string with no spaces; OMARS will add a "-" between the prefix and the generated unique number to form the complete OrderID. Use the prefix to distinguish orders entered by your API service from those entered from other sources.

  3. Allowed IP Addresses:  Required for service
    This is a list of the IP addresses allowed for API clients. You can use it to restrict access to your API service to certain machines, such as your Web servers, which are known to be running the API client. The special value "*" allows clients everywhere to access the service. The value must be a list of IP address in "dot" form, separated by a space and/or comma. For example, 18.18.1.78, 18.183.0.97

Edit Digital Receipt Templates

You should only configure this service if you plan to have Digital Receipts (i.e. email confirmations of orders) sent automatically to either the merchant, the customer, or both. Otherwise it is not necessary.
  1. Use Default Access List: (leave next field empty if checked)
    Access:
    Names the people who are allowed to edit Digital Receipt templates. The people are identified by their Kerberos login name, which is the same as their email address "@mit.edu". E.g. the login name of someone who gets mail at florey@mit.edu would be florey.
  1. Do you have any other requests or comments? (Optional)