OMARS: Order-Entry API
Programming Manual (Java)

Larry Stone, July 2002

OMARS, the Order Management and Reporting Services, is the merchant user's interface to the MIT I/S credit card order processing system. It includes an Application Programming Interface (API) to connect your own Web and E-commerce applications to the system. The API lets client programs enter new orders in your ClearCommerce store just like the point-of-sale Web service does for interactive users.

This manual describes the Java API. This is currently the only API available, although it should be possible to provide API clients in other languages since the client-server communication is based on HTTP-SSL and XML. There are no plans for such ports at this time, however.

Overview: Creating and Entering an Order
Programming with the Order Entry API
Document Contents and Structure
1. OrderDocument
2. OrderResponse
More API Programming: Addresses and Items
Code Examples
Debugging

Features

Defines a simpler and more straightforward interface than the subtle and complex ClearCommerce API. It is much easier to use and faster to learn than the full ClearCommerce interface.
Uses SSL for privacy and client certificate for strong authentication.
Data structures exchanged between client and server are easily extended and changed without the need for a new version of the client library. New features can be added without any changes to the client.
Clients can only execute PreAuth and Auth transactions to create new orders. This enhances security by restricting the use of fraud-prone "secondary" transactions such as credits. Merchants can use the interactive OMARS order management service to mark orders fulfilled, issue credits, void orders, etc.

Overview: Creating and Entering an Order

The typical application calling the Order Entry API creates a single credit-card order, "processes" it (which gets the transaction authorized, or declined, in real time), and relays the results to the customer. An application can process multiple orders, either simutaneously or serially.

The life cycle of each order follows these steps:

Create an OrderDocument object and set the relevant fields. Some data are stored in subordinate structures called Records. There is a set of mandatory fields which must be set.
Call the process() method of the OrderDocument to submit it for processing. This submits the order to the ClearCommerce Engine, which gets it authorized (or declined) by the processor. The process() call returns an OrderResponse object with full details on the status of the transaction, and results such as the order identifier.
Examine the OrderResponse, taking appropriate actions and relaying the information to the customer.

The process() can only be called once on any OrderDocument. To process another transaction, you must create a new OrderDocument.

Programming with the Order Entry API

API Reference

Please see the generated javadoc reference pages for complete details of the API. These show all of the objects and methods:

http://web.mit.edu/ecommerce/www/omars/api/

Minimal Client Program

Here is a code fragment from a very simple client program that creates and processes an order, setting the minimum fields needed:

    import edu.mit.is.ecommerce.api.OrderResponse;
    import edu.mit.is.ecommerce.api.OrderDocument;
    import edu.mit.is.ecommerce.api.OrderException;
    import edu.mit.is.ecommerce.api.Record;

    OrderDocument doc = new OrderDocument();
    Record rec;
    rec = doc.getRoot();
    rec.setField("Type", "PreAuth");
    rec.setField("CardNumber","4242424242424242");
    rec.setField("ExpireMonth","03");
    rec.setField("ExpireYear","14");
    rec.setField("Total","42.13");
    try {
        OrderResponse resp = doc.process("https://omars.mit.edu/mystore_api", "mycert.pem");
        if (resp.getRoot().getField("Status").equals(OrderResponse.APPROVED)) {
            ..report success..
        } else if (resp.getRoot().getField("Status").equals(OrderResponse.DECLINED)) {
            ..tell customer to correct problem and try again..
        } else if (resp.getRoot().getField("Status").equals(OrderResponse.ERROR)) {
            ..tell customer to report error, contact maintainer..
        }
    } catch (OrderException e) {
        ..tell customer to report error, contact maintainer..
    } catch (java.io.IOException e) {
        ..tell customer to report error, contact maintainer..
    }

Note how the "top level" fields are actually set in the root Record of the document, not in the OrderDocument itself. Just copy this code in your own applications.

The separate import statements are shown to demonstrate which packages are used. You can just import edu.mit.is.ecommerce.api.* .

Client Certificates

You will also need a client certificate to gain access to the OMARS API. This is a cryptographic document similar to the personal Web client certificate you use to gain access to interactive OMARS services with your web browser. Keep the certificate in a file on each machine that runs the OMARS API client, since the certificate file is an argument to the OrderDocument.process() method.

IMPORTANT: Certificate Security

The certificate file identifies your organization to the OMARS server. Be careful to protect it from unauthorized access, since it gives anyone with a computer on the internet access to your OMARS store through the API.

Do not send the certificate in cleartext email (PGP-encrypted mail is OK).
Do not put it in an unprotected network file system such as any NFS partition or windows file sharing, or public AFS lockers.
Do store the certificate file with other important, private, Web application and server configuration files -- in a separate directory hierarchy from the Document (on e.g. Apache 1.3).
Take care with your Web server configuration so it does not inadvertently expose files you need to keep private. Turn off all file access by default and only allow a hierarchy of static documents to be "visible" through the Web server.

IMPORTANT: Renew Your Certificate Every Year

Like a personal Web certificate, your OMARS client certificate is only valid for a year from its issuance, in order to protect you from lost or exposed certificates. You must renew it before it expires, or your store will not function.

When you receive a new OMARS certificate, it will be good for exactly 1 year. Plan now to ask to renew it at least two weeks before it expires.

WARNING: It can sometimes take several days to process certificate requests. You MUST remember to renew your certificate before it expires, or your application will be down and there is nothing we can do about it.

We recommend using a automated tool like setting an "Event" in TechTime or a cron job on your computer to remind you to renew your OMARS certificate.

How to Renew your Certificate

To renew your certificate, send mail to chargemit-help mentioning the name of your store or the URL by which you access the API. We will get you the new one by a secure method, such as a floppy disk.

Contents of an OMARS Certificate File

The OMARS certificate is a plain ASCII file containing two PEM-encoded blocks. First is the private key used to construct the certificate (which is a signed public key). Next is the X.509 client certificate. It will look something like this:

  -----BEGIN RSA PRIVATE KEY-----
  Proc-Type: 4,ENCRYPTED
  DEK-Info: DES-CBC,1C6ADB959ECFD677
   
  D0/aBcx1h3fo8GoqKsa60jrW/T08QMydwIkNTlBG2PjJrd8my76GGgtNzMK0KKsr
  pQSQpt082b74HVplOF3sL8OIgt58Sd2L9pznryBjqAkno2krQZu7WL14vjahCCPy
    ....
  omhHiN9bir4McjK1hmA2LTMyzPERBvJQNqDaQBjbosmXVqHxc7kdQQ==
  -----END RSA PRIVATE KEY-----
   
  -----BEGIN CERTIFICATE-----
  MIIC1jCCAj+hAwIBAgIDE8VLMA0GCSqGSIb3DQEBBAUAMGwxCzAJBgNVBAYTAlVT
  pQSQpt082b74HVplOF3sL8OIgt58Sd2L9pznryBjqAkno2krQZu7WL14vjahCCPy
    ....
  omhHiN9bir4McQ==
  -----END CERTIFICATE-----

Running your API Client program

These instructions have only be tested on the Solaris SPARC platform (solaris 2.8) with Java 1.3.1. If you have problems with a later version of the Java runtime environment, try version 1.3.1 instead. It is available on Athena in the java_v1.3.1 locker.

You will need the following libraries in your CLASSPATH:

jdom.jar xercesImpl.jar xmlParserAPIs.jar puretls.jar cryptix32.jar cryptix-asn1.jar omars-client.jar

They should be available in the ecommerce locker, under /mit/ecommerce/omars-current/lib (for the current OMARS release).

When a new version of OMARS is deployed, you will be responsible for updating your copy of the OMARS client library omars-client.jar as well as any necessary upgrades of other libraries. Subscribe to the omars-users mailing list (send mail to omars-users-request@mit.edu) so you will get these announcements.

Document Contents and Structure

The OrderDocument is constructed by an Order Entry API client. It is then "processed" to return an OrderResponse.

OrderDocument

This diagram shows the complete OrderDocument structure. Required fields are shown in bold, and explanatory notes in italics. Each field is shown with contents indicating what belongs there: keywords contain the available choices separated by vertical bars, e.g. this | that. Free-text fields have sample contents in italics. The contents of the fields are surrounded by extra spaces for readability in this example only; when assigning field values you should strip off all leading and trailing spaces.

    <OrderDocument>

        -- Order properties
        <Type> PreAuth | Auth </Type>
        <OrderID> unique order identifier (36 chars) </OrderID>
        <Comments> up to 64 chars of "comment" text </Comments>
        <Mode> P|T|Y|N|R </Mode>  -- (Default is P; Y,N,R are for testing)
        <IPAddress> customer's IP address </IPAddress>
        <Email> customer's email address </Email>

        -- Credit card information
        <CardNumber> credit card number </CardNumber>
        <ExpireMonth> expiration month, 2 digits </ExpireMonth>
        <ExpireYear> expiration year, 2 digits </ExpireYear>
        <CVM> Card Verification Method numbers </CVM>

        -- Order totals
        <TaxExempt> true|false </TaxExempt>
        <StateTax> amount of state tax </StateTax>     -- [see note 1]
        <Shipping> amount of shipping </Shipping>      -- [see note 1]
        <SubTotal> amount of subtotal </SubTotal>   -- [see note 1,2]
        <Total> amount of total </Total>            -- [see note 1,2]

        -- Optional structures
        <BillingAddress>
            <Location>
                <Name> Jack Florey </Name>
                <Company> Mass Tool & Die (screws in all sizes) </Company>
                <Street1> 77 Mass Ave </Street1>
                <Street2> Room 7-013 </Street2>
                <Street3> Third Cubical on the Left </Street3>
                <City> Cambridge </City>
                <State> MA </State>
                <Zip> 02139 </Zip>
                <Country> 840 </Country>      -- Must be 3-digit ISO country code
                <TelVoice> 617-555-1212 </TelVoice>
                <TelFax> 617-555-1212 </TelFax>
             </Location>
        </BillingAddress>

        <ShippingAddress>
             <Location>
                 (same contents as Location tag under BillingAddress above)
             </Location>
        </ShippingAddress>

        <ItemList>
            <Item>                -- Repeated for each line in item list
                <ItemNumber> 1 </ItemNumber>     -- "line number", 1..N
                <Qty> 1 </Qty>                   -- quantity of units ordered
                <ProductCode> 666-999 </ProductCode>  -- (up to 12 chars) SKU or stock number
                <Id> widget01 </Id>                   -- (up to 40 chars) Item Identifier
                <Desc> LH Widget </Desc>    -- (64 chars) Product description
                <Price> 1.39 </Price>  -- [1] unit price, decimal dollars
                <TaxExempt> true/false </TaxExempt>  -- tax-exempt status, "true" or "false"
                <StateTax> 0.09 </StateTax>          -- [1] total tax for line, decimal dollars
                <Shipping> 1.06 </Shipping>          -- [1] total shipping for line, decimal dollars
                <Total> 1.48 </Total>                -- [1] total charge for line, incl tax
                <UnitMeasure> thing </UnitMeasure>  -- (up to 12 chars) unit of measurements (lbs, gross, etc)
            </Item>
        </ItemList>

Notes:

A monetary value is specified as a positive decimal number of dollars, without the currency symbol. For example, "2.66".
Unless the order includes an item list, at least one of the Total and SubTotal fields must be set. See the descriptions of each field, below, for details.

Detailed Explanation of `OrderDocument` Fields

Type

Required; Declares what kind of transaction to execute. PreAuth just "authorizes" the sale and reserves the funds for the total in the customer's account, while Auth does that and also captures the funds for the merchant (although no money is actually transferred until settlement, usually at the end of the day). A PreAuth transaction must be captured ("fulfilled") later, using the interactive OMARS Order Management service. Use PreAuth when the customer is buying hard goods, such as books, which are not delivered immediately. The merchant is only allowed to capture funds after the goods have been delivered.

OrderID

Optional, assigns the order identifier for this transaction. It may be up to 36 characters long and must be unique among all other orders created in your store. Usually the only reason to assign the OrderID is when you want it to match the identifier in another order management system, such as your invoice number. If this field is not set, ClearCommerce will assign a unique identifier.

Comments

Optional. An arbitrary string of up to 64 characters which gets associated with this order. Use it to cache auxiliary information such as references to other administrative objects like a batch or invoice. It can be viewed in the OMARS Order Management and Transaction Report services.

Mode

Optional. Sets the operational mode of the transaction in ClearCommerce. You should only need to set this for testing; the API server has its own default. The mode can be set to:

Y -- Test mode that always approves the transaction, does not send it to the processor.
N -- Test mode that always declines the transaction, does not send it to the processor.
R -- Test mode that randomly approves or declines the transaction, does not send it to the processor.
T -- Transaction is sent to the configured "test" processor. Merchants should never need to use this mode.
P -- Transaction is sent to the configured production processor.

IPAddress

Optional, records an IP address with the order. Use this to store the IP address of the customer using your e-commerce application if it might be helpful to have it later.

Email

Optional, the email address of the customer making the order. If your ClearCommerce store is configured to send digital receipts to customers, the messages will be sent to this address.

CardNumber

Required, the credit card number to charge for this order. The number should be 15 or 16 digits. It may include dashes or spaces to separate the groups of 4 digits, like the way the number is printed on a card. Limit of 40 characters.

ExpireMonth

Required, the number of the month in which the card expires. January is 01. It must be a two-digit number with a leading zero if needed.

ExpireYear

Required, last two digits of the year in which the card expires (e.g. "06").

CVM

Optional. The CVM is a 3- or 4-digit code found on the physical credit card, usually on the back near the signature. Including it with the information sent to the card processor demonstrates that you (or the customer entering an e-commerce order) has possession of the physical card. This increases security and gets the merchant a more favorable discount rate on the transaction.

TaxExempt

Optional, a keyword value, either true or false. Declares that the order is tax-exempt (although if you specify a StateTax amount it will still get added into the total). The default is false. This is not really needed, since you can just leave out the tax amounts on untaxed orders.

StateTax

Optional, the total amount of state sales tax to be charged on the order. This figure is added to the SubTotal field when computing the total to be charged.

Although it is not necessary to separate out the tax, we strongly recommend you do so. You can then get ClearCommerce to produce cumulative reports of the state tax collected, which helps with accounting. Very few items sold by MIT merchants are subject to sales tax anyway, so this is usually not even a consideration.

Like all amount figures this must be a decimal number without any other puctuation or currency symbols.

Shipping

Optional, the total amount of shipping charges on the order. This figure is added to the SubTotal field when computing the total to be charged. Like all amount figures this must be a decimal number without any other puctuation or currency symbols.

SubTotal

Required unless an item list or explicit Total field is specified. This is the amount to be charged for goods and services ordered. It is added to the StateTax and Shipping fields to compute the total amount to charge for the order. Like all amount figures this must be a decimal number without any other puctuation or currency symbols.

Total

Required unless an item list or explicit SubTotal field is specified. This is the total amount to be charged for the order. If an item list or other amount fields were specified, this total must match the sum of the subtotal, tax, and shipping. Like all amount figures this must be a decimal number without any other puctuation or currency symbols.

BillingAddress

Optional, a sub-record describing the customer's credit card billing address. It contains the name as it appears on the credit card, and the address to which the credit card statements and bills are sent. This information is used by the credit card processor to help validate the customer, and when it is correct you will get a more favorable discount rate.

See the section below describing Location fields for more details.

ShippingAddress

Optional, a sub-record listing the name and address to which the order is to be shipped. This can also be used for other purposes according to the application; for example, it can list the name of the donor of an alumni fund contribution, when it differs from the name on the credit card used to make the payment.

See the section below describing Location fields for more details.

ItemList

Optional, a sub-record containing a list of records describing the items ordered. The OMARS Order Management service will display this item list, and let the store administrator mark the individual items as fulfilled or credited when managing the order. In some cases ClearCommerce will also send item-list information to the credit card processor.

See the section below describing Item Fields for more details on constructing the item list.

Fields in `Location` sub-Records

Each of the address fields, BillingAddress and ShippingAddress, contains a sub-Record named Location. This record may include the following fields:

Name: The person's name, with all titles & etc. Up to 60 characters long. In the Billing Address, this field should match the name on the credit card.
This field in the Billing address is used for address verification, so make all efforts to include it, since a matching address will get you a better discount rate on the transaction.
Company: Company name associated with the address. For credit cards issued to a company or organization, it is part of the billing address. May be up to 40 characters long.
Street1: First line of the street address, which should contain the street name and number. Up to 60 characters.
This field in the Billing address is used for address verification, so make all efforts to include it, since a matching address will get you a better discount rate on the transaction.
Street2: Optional second line of the street address. Up to 60 characters.
Street3: Optional third line of the street address. Up to 60 characters.
City: The name of the city, may be up to 25 characters.
State: State (or province) in the address. Up to 25 characters long. Use the standard two-letter abbreviations for states in US addresses.
Zip: The ZIP code (for US addresses) or postal code. May be up to 20 characters.
This field in the Billing address is used for address verification, so make all efforts to include it, since a matching address will get you a better discount rate on the transaction.
Country: The country is described not by its name, but by its 3-digit numeric country code from the ISO 3166 encoding. E.g. the United States is "840". For more information about country codes, see this ISO index page, although it does not list the numeric codes. Listings maintained by other agencies are available at:
http://www.tu-berlin.de/zrz/dienste/netz/mail/iso-3166.html http://ftp.ics.uci.edu/pub/ietf/http/related/iso3166.txt
TelVoice: Voice telephone number, up to 30 characters long.
TelFax: FAX telephone number, up to 30 characters long.

Fields in `Item` sub-Records

The ItemList sub-Record is composed of a list of Item records. Note that four of the Item fields are required, and must be present in each Item record: ItemNumber, Qty, Desc, and Price. An Item record may contain the fields:

ItemNumber: Required; The "line number" of this item in the order, ideally numbered from 1 up. Must be an integer (in String form, of course).
Qty: Required; The number of units of the item ordered. Must be an integer, up to 7 digits.
ProductCode: Merchant-defined identifier assocated with the item, such as a UPC, SKU or ISBN code. May be up to 12 characters long.
Id: A separate identifier for the item, up to 40 characters long. It does not have to be unique in the order.
Desc: Human-readable, brief, description of the item. May be up to 64 characters long.
Price: Required: Price of one unit of the item, in decimal dollars. Like all amounts in this API, it is written without punctuation or currency symbols. The price multiplied by the figure in Qty is the goods subtotal for this line of the item list.
TaxExempt: Optional, a keyword value, either true or false. Declares that the item is tax-exempt (although if you specify a StateTax amount it will still get added into the total). The default is false. This is not really needed, since you can just leave out the tax amounts on untaxed items.
StateTax: Optional: Amount of state (sales) tax to be charged for the entire line. Note that this is not the tax for just one unit of the item. It is added into the total tax for the order, unless the order has a StateTax field.
Although it is not necessary to separate out the tax, we strongly recommend you do so. You can then get ClearCommerce to produce cumulative reports of the state tax collected, which helps with accounting. Very few items sold by MIT merchants are subject to sales tax anyway, so this is usually not even a consideration.
Shipping: Optional: Amount of shipping to be charged for the entire line. Note that this is not the shipping for just one unit of the item. It is added into the total shipping for the order, unless the order has a Shipping field.
Total: Optional: The total amount to be charged for this line of the item list. It is computed automatically if this field is left out. The total must match the sum of the item price times quantity, and the tax and shipping amounts for the line.
UnitMeasure: Optional: Describes the measurement scale or name for a unit of the item, such as "lbs", "kilograms", "gross", etc. May be up to 12 characters.

Structure of Order Response

The OrderResponse document returned by the process() method has the following structure. Fields shown in bold are always present. The presence of other fields depends on the value of <

    <OrderResponse>
        <Status> APPROVED | DECLINED | ERROR  </Status>
        <Time> timestamp  </Time>
        <OrderID> unique order identifier (36 chars) </OrderID>
        <ErrorSummary> Explanation of ERROR or DECLINED status </Message>
        <AuthCode> authorization code returned by processor </AuthCode>
        <Span> credit card number span  </Span>
        <Amount> 0.00  </Amount>
        <ErrorList>
          <Error>
            <ContextId> context identifier </ContextId>
            <ResourceId> resource identifier </ResourceId>
            <Severity> severity code </Severity>
            <Message> message text </Message>
            <AdvisedAction> action code </AdvisedAction>
            <DataState> data loss code </DataState>
          </Error>
            [...]
        </ErrorList>
    </OrderResponse>

Detailed Explanation of `OrderResponse` Fields

Status

A keyword indicating the success or failure of the order processing. It will match one of the following constants:

OrderResponse.APPROVED: Order was approved, all fields below except ErrorSummary will contain data.
OrderResponse.DECLINED: Order was declined by the credit card processor (although it was correctly assembled and presented). The ErrorSummary field contains an explanation, and Error has the details.
OrderResponse.ERROR: The order was not acceptable to the processing system, perhaps because of an internal inconsistency, missing fields, or illegal value. The ErrorSummary field contains the reason it was rejected, and Error has the details.

Time

The timestamp of when the order was processed. It is expressed as the number of milliseconds since the beginning of January 1, 1970, GMT. You can initialize a java.util.Date object with this number. This field is always present in APPROVED and DECLINED responses, but it is not included in all ERROR responses.

OrderID

The ClearCommerce identifier for this order. If the request did not include an OrderID field, it was automatically assigned, so the application can only discover it by reading this field. Use this identifier to find the order in the OMARS Order Management service.

ErrorSummary

This field is only set when the transaction fails. It contains a human-readable text string summarizing the reason for the failure. When ErrorSummary is set, the subrecords under ErrorList will have more detailed and structured information about the failure.

AuthCode

This is a 6-character identifier assigned to the transaction by the credit card processor, only when the transaction is approved. It is useful to have if the transaction needs to be traced later at the credit card processor.

Span

This returns the "span" of the credit card number, a fragment which is enough to identify the card but too little to derive the card number and use it in other transactions. It is thus safe to store online, display on the screen and email in plain text. It is eight digits, derived from the first four and last four digits of the card number. Always display the span, not the credit card number, whenever you need to identify the credit card. It is a good practice to include it in receipts so the customer can tell which card they used. Insert an ellipsis or stars in between the first four and last four digits to show how the card number was elided, e.g. "6011*********4242".

Amount

The total amount of money billed to the customer in this transaction, in decmial dollars. Also useful to show to the customer on a receipt. It should always match the Total field from the order.

ErrorList

When the Status field is either DECLINED or ERROR, this field is a list of Error sub-records. These are the error messages and other information returned by the ClearCommerce Engine. Each Error record contains the following fields:

ContextId

Symbolic name of the context (i.e. a subsystem or component of the Engine) which produced the error. Combined with the ResourceId it uniquely identifies an error message. It is usually a short string such as "ACH" or "Payment".

ResourceId

The numeric code associated an error message. It is unique within a context.

Severity

A numeric code describing how urgency of the error described in this message. The possible values, from 0-8, are:

        0   Success                   5   Error
        1   Debug                     6   Critical
        2   Informational             7   Alert
        3   Notice                    8   Emergency
        4   Warning

Message

The text of the message describing the error.

AdvisedAction

A numeric code describing a suggested course of action, as follows:

"Urgent. Immediate action is required to address an existing problem."
"Attention. Action is required to address a potential problem."
"None. No action is required."

DataState

A numeric code describing whether the error resulted in data loss, as follows:

Data has been lost.
Data can be lost without user intervention.
Data is not in danger of being lost.

More API Programming: Addresses and Items

Now that you have seen all of the OrderDocument fields and sub-records, the method of adding addresses and items to the order can be explained.

Semantics of the Optional Sub-records

Adding a BillingAddress to your order is always a good idea, since the processor will try to match it with Address Verification Service (AVS) and get you a better discount rate. You must include the Name, Street1, and Zip fields for AVS to get a match. The billing name also appears in reports produced by the OMARS interactive services, where it can help you locate an order.

The ShippingAddress is only needed if your application has some use for it. You will see it again in the detailed order report of the OMARS Order Management service, but otherwise it is not used by the system. ClearCommerce can compute shipping charges automatically based on this address but we have no way to use the feature at this time.

Adding an ItemList gives several benefits: It documents the goods purchased in a way you can see later through the OMARS Order Management interface. That service also lets you fullfil or credit individual item lines in the order. In some cases, the item list is sent to the credit card processor and will appear on the customer's credit card statement.

Code Examples

This code fragment adds a billing address to an OrderDocument variable doc. Note how a BillingAddress sub-record is added to the document root and a Location is added to it. The Location contains the address fields.

    Record addr = doc.getRoot().addRecord("BillingAddress").addRecord("Location");
    addr.setField("Name", "Jack Florey");
    addr.setField("Street1", "60 Vassar St.");
    addr.setField("Zip", "02139");

The code to add an item list is similar, except that more than one Item record can be added to the ItemList. Also, when you have an item list, the order does not need a SubTotal or Total field, since the subtotal is computed automatically from the sum of all item lines. If you do include a SubTotal, it must match the sum of all item prices, and if you include a Total field, it must match the sum of the subtotal plus any tax and shipping amounts.

This example adds three item lines to the order:

    Record iList = doc.getRoot().addRecord("ItemList");
    Record item = iList.addRecord("Item");
    item.setField("ItemNumber", "1");
    item.setField("Qty", "3");
    item.setField("Desc", "Slide-rule cozy");
    item.setField("Price", "1.99");
    item = iList.addRecord("Item");
    item.setField("ItemNumber", "2");
    item.setField("Qty", "1");
    item.setField("Desc", "Official MIT Propellor Beanie");
    item.setField("Price", "5.99");
    item = iList.addRecord("Item");
    item.setField("ItemNumber", "3");
    item.setField("Qty", "1");
    item.setField("Desc", "2-inch \"Nerd Pride\" pin");
    item.setField("Price", "1.00");

Error Messages: This code fragment prints all of the error messages in the OrderResponse response, which is assumed to be the result of an error or declined transaction:

            Record errorList = response.getRecord("ErrorList");
            if (errorList != null) {
                Record err;
                for (err = errorList.getFirstRecord("Error");
                     err != null;
                     err = errorList.getNextRecord("Error")) {
                    System.out.println("Error Record: ContextId="+
                      err.getField("ContextId")+
                      ", ResourceId="+err.getField("ResourceId")+
                      ", AdvisedAction="+err.getField("AdvisedAction")+
                      ", DataState="+err.getField("DataState")+
                      "\n  Severity="+err.getField("Severity")+
                      ", Message="+err.getField("Message"));
                    }
            }

Debugging

If you have any trouble building an OrderDocument, or would just like the visualize the result, use the write() method to print it. OrderResponse documents have this method too. This example writes a formatted view of the document to the standard error stream, which Web servlet engines usually record in a log file:

        doc.write(System.err);

NOTE: This produces a valid XML document, so if any of the field values contain XML metacharacters they will be escaped. The following characters will be printed as entity strings:

                >   prints as    &gt;
                <   prints as    &lt;
                &   prints as    &amp;

OMARS: Order-Entry API Programming Manual (Java)

Contents