Network Working Group D. Eastlake
Request for Comments: 3106 Motorola
Obsoletes: 2706 T. Goldstein
Category: Informational Brodia
April 2001
ECML v1.1: Field Specifications for E-Commerce
Status of this Memo
This memo provides information for the Internet community. It does
not specify an Internet standard of any kind. Distribution of this
memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2001). All Rights Reserved.
IESG Note:
This document specifies version 1.1 of ECML and obsoletes RFC 2706
which specifies version 1.0 of ECML. Both version 1.0 and 1.1 of ECML
are products of the ECML alliance which is described in section 1.1
of this document. The reader should note that version 2.0 of ECML is
under development (as of the publication of this RFC) in the IETF in
the TRADE Working Group.
Abstract
Customers are frequently required to enter substantial amounts of
information at an Internet merchant site in order to complete a
purchase or other transaction, especially the first time they go
there. A standard set of information fields is defined as the first
version of an Electronic Commerce Modeling Language (ECML) so that
this task can be more easily automated, for example by wallet
software that could fill in fields. Even for the manual data entry
case, customers will be less confused by varying merchant sites if a
substantial number adopt these standard fields. In addition, some
fields are defined for merchant to consumer communication.
Eastlake & Goldstein Informational [Page 1]
RFC 3106 ECom Field Names April 2001
Acknowledgements
The following persons, in alphabetic order, contributed substantially
to the material herein:
George Burne
Joe Coco
Jon Parsons
James Salsman
David Shepherd
Kevin Weller
Table of Contents
1. Introduction.................................................. 2
1.1 The ECML Alliance............................................ 3
1.2 Relationship to Other Standards.............................. 4
1.3 Areas Deferred to Future Versions............................ 4
2. Field Definitions and DTD..................................... 4
2.1 Field List and Descriptions.................................. 4
2.1.1 Field List................................................. 5
2.1.2 Field Foot Notes........................................... 7
2.2 Use in HTML.................................................. 10
2.3 An ECML 1.1 XML DTD.......................................... 11
3. Using The Fields.............................................. 13
3.1 Presentation of the Fields................................... 13
3.2 Methods and Flow of Setting the Fields....................... 14
3.3 HTML Example................................................ 14
4. Security and Privacy Considerations........................... 16
References....................................................... 16
Appendix: Changes from ECML 1.0.................................. 18
Authors' Addresses............................................... 19
Full Copyright Statement......................................... 20
1. Introduction
Today, numerous merchants are successfully conducting business on the
Internet using HTML-based forms. The data formats used in these
forms vary considerably from one merchant to another. End-users find
the diversity confusing and the process of manually filling in these
forms to be tedious. The result is that many merchant forms,
reportedly around two thirds, are abandoned during the fill in
process.
Software tools called electronic wallets can help this situation. A
digital wallet is an application or service that assists consumers in
conducting online transactions by allowing them to store billing,
shipping, payment, and preference information and to use this
Eastlake & Goldstein Informational [Page 2]
RFC 3106 ECom Field Names April 2001
information to automatically complete merchant interactions. This
greatly simplifies the check-out process and minimizes the need for a
consumer to think about and complete a merchant's form every time.
Digital wallets that fill forms have been successfully built into
browsers, as proxy servers, as helper applications to browsers, as
stand-alone applications, as browser plug-ins, and as server-based
applications. But the proliferation of electronic wallets has been
hampered by the lack of standards.
ECML (Electronic Commerce Modeling Language, ) provides
a set of simple guidelines for web merchants that will enable
electronic wallets from multiple vendors to fill in their web forms.
The end-result is that more consumers will find shopping on the web
to be easy and compelling.
Version 1.1 has been enhanced over Version 1.0 [RFC 2706] as
described in the appendix to this document. These enhancements
include support for communication from the merchant to the wallet.
This information can be used by the wallet to present transaction
information and possibly signed receipts. The format of the
signatures for receipts is not specified in this document.
Multiple wallets and multiple merchants interoperably support ECML.
This is an open standard. ECML is designed to be simple. Neither
Version 1.0 nor Version 1.1 of the project add new technology to the
web. A merchant can adopt ECML and gain the support of these
multiple Wallets by making very simple changes to their site. Use of
ECML requires no license.
1.1 The ECML Alliance
The set of fields documented herein was developed by the ECML
Alliance (www.ecml.org) which now includes, in alphabetic order, the
fifteen Steering Committee members listed below and numerous General
Members some of whom are listed on the ECML web site.
1. American Express (www.americanexpress.com>
2. AOL (www.aol.com)
3. Brodia (www.brodia.com)
4. Compaq (www.compaq.com)
5. CyberCash (www.cybercash.com)
6. Discover (www.discovercard.com)
7. FSTC (www.fstc.org)
8. IBM (www.ibm.com)
9. Mastercard (www.mastercard.com)
10. Microsoft (www.microsoft.com)
11. Novell (www.novell.com>
12. SETCo (www.setco.org)
Eastlake & Goldstein Informational [Page 3]
RFC 3106 ECom Field Names April 2001
13. Sun Microsystems (www.sun.com)
14. Trintech (www.trintech.com>
15. Visa International (www.visa.com)
1.2 Relationship to Other Standards
The ECML fields were initially derived from and are consistent with
the W3C P3P base data schema at
.
ECML Version 1.1 is not a replacement or alternative to SSL/TLS [RFC
2246], SET [SET], XML [XML], or IOTP [RFC 2801]. These are important
standards that provide functionality such as non-repudiatable
transactions, automatable payment scheme selection, and smart card
support.
ECML may be used with any payment mechanism. It simply allows a
merchant to publish consistent simple web forms. Information on the
use of the ECML fields with W3C P3P protocol is available at
which also includes some
proposed extension fields. These extension fields may be included in
a future version of ECML.
1.3 Areas Deferred to Future Versions
Considerations for business purchasing cards, non-card payment
mechanisms, wallet activation, privacy related mechanisms, additional
payment mechanisms, currency exchange, and any sort of "negotiation"
were among the areas deferred to consideration in future versions.
Hidden or other special fields were minimized.
2. Field Definitions and DTD
The ECML Standard is primarily the definition and naming of fields.
These fields can be encoded in a variety of syntaxes and protocols.
Section 2.1 below lists and describes the fields, Section 2.2 gives
additional notes on HTML usage of the fields, and Section 2.3
provides an XML DTD for use with the fields.
2.1 Field List and Descriptions
The fields are listed below along with the minimum data entry size to
allow. Note that these fields are hierarchically organized as
indicated by the embedded underscore ("_") characters. Appropriate
data transmission mechanisms may use this to request and send
aggregates, such as Ecom_Payment_Card_ExpDate to encompass all the
Eastlake & Goldstein Informational [Page 4]
RFC 3106 ECom Field Names April 2001
date components or Ecom_ShipTo to encompass all the ship to
components that the consumer is willing to provide. The labeling,
marshalling, unmarshalling of the components of such aggregates
depends on the data transfer protocol used.
2.1.1 Field List
IMPORTANT NOTE: "MIN" in the table below is the MINIMUM DATA SIZE TO
ALLOW FOR ON DATA ENTRY. It is NOT the minimum size for valid
contents of the field and merchant software should, in most
cases, be prepared to receive a longer or shorter value.
Merchant dealing with areas where, for example, the
state/province name or phone number is longer than the "Min"
given below must obviously permit longer data entry. In some
cases, however, there is a maximum size that makes sense and
where this is the case, it is documented in a Note for the
field.
The following fields are used to communicate from the customer
to the merchant:
FIELD NAME Min Notes
ship to title Ecom_ShipTo_Postal_Name_Prefix 4 ( 1)
ship to first name Ecom_ShipTo_Postal_Name_First 15
ship to middle name Ecom_ShipTo_Postal_Name_Middle 15 ( 2)
ship to last name Ecom_ShipTo_Postal_Name_Last 15
ship to name suffix Ecom_ShipTo_Postal_Name_Suffix 4 ( 3)
ship to company name Ecom_ShipTo_Postal_Company 20
ship to street line1 Ecom_ShipTo_Postal_Street_Line1 20 ( 4)
ship to street line2 Ecom_ShipTo_Postal_Street_Line2 20 ( 4)
ship to street line3 Ecom_ShipTo_Postal_Street_Line3 20 ( 4)
ship to city Ecom_ShipTo_Postal_City 22
ship to state/province Ecom_ShipTo_Postal_StateProv 2 ( 5)
ship to zip/postal code Ecom_ShipTo_Postal_PostalCode 14 ( 6)
ship to country Ecom_ShipTo_Postal_CountryCode 2 ( 7)
ship to phone Ecom_ShipTo_Telecom_Phone_Number 10 ( 8)
ship to email Ecom_ShipTo_Online_Email 40 ( 9)
bill to title Ecom_BillTo_Postal_Name_Prefix 4 ( 1)
bill to first name Ecom_BillTo_Postal_Name_First 15
bill to middle name Ecom_BillTo_Postal_Name_Middle 15 ( 2)
bill to last name Ecom_BillTo_Postal_Name_Last 15
bill to name suffix Ecom_BillTo_Postal_Name_Suffix 4 ( 3)
bill to company name Ecom_BillTo_Postal_Company 20
bill to street line1 Ecom_BillTo_Postal_Street_Line1 20 ( 4)
bill to street line2 Ecom_BillTo_Postal_Street_Line2 20 ( 4)
bill to street line3 Ecom_BillTo_Postal_Street_Line3 20 ( 4)
Eastlake & Goldstein Informational [Page 5]
RFC 3106 ECom Field Names April 2001
bill to city Ecom_BillTo_Postal_City 22
bill to state/province Ecom_BillTo_Postal_StateProv 2 ( 5)
bill to zip/postal code Ecom_BillTo_Postal_PostalCode 14 ( 6)
bill to country Ecom_BillTo_Postal_CountryCode 2 ( 7)
bill to phone Ecom_BillTo_Telecom_Phone_Number 10 ( 8)
bill to email Ecom_BillTo_Online_Email 40 ( 9)
receipt to (32)
receipt to title Ecom_ReceiptTo_Postal_Name_Prefix 4 ( 1)
receipt to first name Ecom_ReceiptTo_Postal_Name_First 15
receipt to middle name Ecom_ReceiptTo_Postal_Name_Middle 15 ( 2)
receipt to last name Ecom_ReceiptTo_Postal_Name_Last 15
receipt to name suffix Ecom_ReceiptTo_Postal_Name_Suffix 4 ( 3)
receipt to company name Ecom_ReceiptTo_Postal_Company 20
receipt to street line1 Ecom_ReceiptTo_Postal_Street_Line1 20 ( 4)
receipt to street line2 Ecom_ReceiptTo_Postal_Street_Line2 20 ( 4)
receipt to street line3 Ecom_ReceiptTo_Postal_Street_Line3 20 ( 4)
receipt to city Ecom_ReceiptTo_Postal_City 22
receipt to state/province Ecom_ReceiptTo_Postal_StateProv 2 ( 5)
receipt to postal code Ecom_ReceiptTo_Postal_PostalCode 14 ( 6)
receipt to country Ecom_ReceiptTo_Postal_CountryCode 2 ( 7)
receipt to phone Ecom_ReceiptTo_Telecom_Phone_Number 10 ( 8)
receipt to email Ecom_ReceiptTo_Online_Email 40 ( 9)
name on card Ecom_Payment_Card_Name 30 (10)
card type Ecom_Payment_Card_Type 4 (11)
card number Ecom_Payment_Card_Number 19 (12)
card verification value Ecom_Payment_Card_Verification 4 (13)
card expire date day Ecom_Payment_Card_ExpDate_Day 2 (14)
card expire date month Ecom_Payment_Card_ExpDate_Month 2 (15)
card expire date year Ecom_Payment_Card_ExpDate_Year 4 (16)
card protocols Ecom_Payment_Card_Protocol 20 (17)
consumer order ID Ecom_ConsumerOrderID 20 (18)
user ID Ecom_User_ID 40 (19)
user password Ecom_User_Password 20 (19)
schema version Ecom_SchemaVersion 30 (20)
wallet id Ecom_WalletID 40 (21)
end transaction flag Ecom_TransactionComplete - (22)
Eastlake & Goldstein Informational [Page 6]
RFC 3106 ECom Field Names April 2001
The following fields are used to communicate from the merchant to the
consumer:
FIELD NAME Min Notes
merchant home domain Ecom_Merchant 128 (23)
processor home domain Ecom_Processor 128 (24)
transaction identifier Ecom_Transaction_ID 128 (25)
transaction URL inquiry Ecom_Transaction_Inquiry 500 (26)
transaction amount Ecom_Transaction_Amount 128 (27)
transaction currency Ecom_Transaction_CurrencyCode 3 (28)
transaction date Ecom_Transaction_Date 80 (29)
transaction type Ecom_Transaction_Type 40 (30)
transaction signature Ecom_Transaction_Signature 160 (31)
end transaction flag Ecom_TransactionComplete - (22)
FIELD NAME Min Notes
IMPORTANT NOTE: "MIN" in the table above is the MINIMUM DATA SIZE TO
ALLOW FOR ON DATA ENTRY. It is NOT the minimum size for valid
contents of the field and merchant software should, in most
cases, be prepared to receive a longer or shorter value.
Merchant dealing with areas where, for example, the
state/province name or phone number is longer than the "Min"
given below must obviously permit longer data entry. In some
cases, however, there is a maximum size that makes sense and
this is documented in a Note for the field.
2.1.2 Field Foot Notes
( 1) For example: Mr., Mrs., Ms., Dr. This field is commonly not
used.
( 2) May also be used for middle initial.
( 3) For example: Ph.D., Jr. (Junior), 3rd, Esq. (Esquire). This
field is commonly not used.
( 4) Address lines must be filled in the order line1, then line2, and
last line3.
( 5) 2 characters are the minimum for the US and Canada, other
countries may require longer fields. For the US use 2 character US
Postal state abbreviation.
Eastlake & Goldstein Informational [Page 7]
RFC 3106 ECom Field Names April 2001
( 6) Minimum field lengths for Postal Code will vary based on
international market served. Use 5 character or 5+4 ZIP for the US
and 6 character postal code for Canada. The size given, 14, is
believed to be the maximum required anywhere in the world.
( 7) Use [ISO 3166] standard two letter codes. See
for country
names.
( 8) 10 digits are the minimum for numbers local to the North
American Numbering Plan (: US, Canada and a
number of smaller Caribbean and Pacific nations (but not Cuba)),
other countries may require longer fields. Telephone numbers are
complicated by differing international access codes, variant
punctuation of area/city codes within countries, confusion caused by
the fact that the international access code in the NANP region is
usually the same as the "country code" for that area (1), etc. It
will probably be necessary to use heuristics or human examination
based on the telephone number and addresses given to figure out how
to actually call a customer. It is recommend that an "x" be placed
before extension numbers.
( 9) For example: jsmith@example.com
(10) The name of the cardholder.
(11) Use the first 4 letters of the association name:
AMER American Express
BANK Bankcard (Australia)
DC DC (Japan)
DINE Diners Club
DISC Discover
JCB JCB
MAST Mastercard
NIKO Nikos (Japan)
SAIS Saison (Japan)
UC UC (Japan)
UCAR UCard (Taiwan)
VISA Visa
(12) Includes the check digit at end but no spaces or hyphens [ISO
7812]. The Min given, 19, is the longest number permitted under the
ISO standard.
(13) An additional cardholder verification number printed on the card
(but not embossed or recorded on the magnetic stripe) such as
American Express' CIV, MasterCard's CVC2, and Visa's CVV2 values.
Eastlake & Goldstein Informational [Page 8]
RFC 3106 ECom Field Names April 2001
(14) The day of the month. Values: 1-31. A leading zero is ignored
so, for example, 07 is valid for the seventh day of the month.
(15) The month of the year. Jan - 1, Feb - 2, March - 3, etc.;
Values: 1-12. A leading zero is ignored so, for example, 07 is valid
for July.
(16) The value in the wallet cell is always four digits, e.g., 1999,
2000, 2001, ...
(17) A space separated list of protocols available in connection with
the specified card. Initial list of case insensitive tokens:
none
set
setcert
iotp
echeck
simcard
phoneid
"Set" indicates usable with SET protocol (i.e., is in a SET wallet)
but does not have a SET certificate. "Setcert" indicates same but
does have a set certificate. "iotp" indicates the IOTP protocol [RFC
2801] is supported at the customer. "echeck" indicates that the
eCheck protocol [eCheck] is supported at the customer. "simcard"
indicates use the transaction instrument built into a Cellphone
subscriber for identification. "phoneid" indicates use the
transaction instrument of a phone bill instrument. "None" indicates
that automatic field fill is operating but there is no SET wallet or
the card is not entered in any SET wallet.
(18) A unique order ID generated by the consumer software.
(19) The user ID and password fields are used in cases where the user
has a pre-established account with the merchant.
(20) URI indicating version of this set of fields. Usually a hidden
field. Equal to "http://www.ecml.org/version/1.1" for this version.
(21) A string to identify the source and version of the form fill
software that is acting on behalf of the user. Should contain
company and/or product name and version. Example "Wallets Inc.,
SuperFill, v42.7". Usually a hidden field.
(22) A flag to indicate that this web-page/aggregate is the final one
for this transaction. Usually a hidden field.
Eastlake & Goldstein Informational [Page 9]
RFC 3106 ECom Field Names April 2001
(23) Merchant domain name such as www.merchant.example. This is
usually a hidden field.
(24) Gateway transaction processor who is actually accepting the
payment on behalf of the merchant in home domain such as
www.processor.example. This is usually a hidden field.
(25) A Transaction identification string whose format is specific to
the processor. This is usually a hidden field.
(26) A URL that can be invoke to inquire about the transaction. This
is usually a hidden field.
(27) The amount of the transaction in ISO currency format. This is
two integer numbers with a period in between but no other currency
marks (such as a $ dollar sign). This is usually a hidden field.
(28) This is the three letter ISO currency code. For example, for US
dollars it is USD. This is usually a hidden field.
(29) ISO Transaction date. This is usually a hidden field.
(30) The type of the transaction (either debit or credit) if known.
This is usually a hidden field.
(31) The signature of the encoded certificate. This is usually a
hidden field.
(32) The Receipt To fields are used when the Bill To entity,
location, or address and the Receipto entity, location, or address
are different. For example, when using some forms of Corporate
Purchasing Cards or Agent Purchasing Cards, the individual card
holder would be in the Receipt To fields and the corporate or other
owner would be in the Bill To fields.
2.2 Use in HTML
The normal use of ECML in HTML is as a form with input field names
identical to those given in section 2.1 above. In general,
tags with type text, hidden, and password must be supported as must