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-Commerce2.1.1 Field List
3.3 HTML Example
<FORM action=http://ecom.example.com method=POST>
Please enter card information:
<p>Your name on the card
<INPUT type=text name=Ecom_Payment_Card_Name SIZE=40>
<br>The card number
<INPUT type=text name=Ecom_Payment_Card_Number SIZE=19>
<br>Expiration date (MM YY)
<INPUT type=text name=Ecom_Payment_Card_ExpDate_Month SIZE=2>
<INPUT type=text name=Ecom_Payment_Card_ExpDate_Year SIZE=4>
<INPUT type=hidden name=Ecom_Payment_Card_Protocol>
<INPUT type=hidden name=Ecom_SchemaVersion
value=http://www.ecml.org/version/1.1>
<br>
<INPUT type=submit value=submit><INPUT type=reset>
</FORM>
| |||||
The following fields are used to communicate from the customer to the merchant
ship to FIELD NAME Min Notes title Ecom_ShipTo_Postal_Name_Prefix 4 1 first name """._First 15 middle name """._Middle 15 2 last name """._Last 15 name suffix """._Suffix 4 3 company name """_Company 20 street line1 """_Street_Line1 20 4 street line2 """_Street_Line2 20 4 street line3 """_Street_Line3 20 4 city """_City 22 state/province """_StateProv 2 5 zip/postal code """_PostalCode 14 6 country """_CountryCode 2 7 phone .._Telecom_Phone_Number 10 8 email .._Online_Email 40 9 |
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 .._Inquiry 500 26 transaction amount .._Amount 128 27 transaction currency .._CurrencyCode 3 28 transaction date .._Date 80 29 transaction type .._Type 40 30 transaction signature .._Signature 160 31 end transaction flag Ecom_TransactionComplete - 22 |
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 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.
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
8 10 digits are the minimum for numbers local to the North
American Numbering Plan (
9 For example: jsmith@example.com
10 The name of the cardholder.
11 Use the first 4 letters of the association name:
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.
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:
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.
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.
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.
IESG Note
AcknowledgementsA
The following persons, in alphabetic order, contributed substantially
to the material herein:
George Burne,
Joe Coco,
Jon Parsons,
James Salsman,
David Shepherd,
Kevin Weller
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
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,
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
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
<http://www.w3.org/TR/WD-P3P/basedata.html>.
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
<http://www.w3.org/TR/P3P-for-ecommerce>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
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.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, <INPUT>
tags with type text, hidden, and password must be supported as must
<SELECT>tags.
Internationalization in HTML is limited. The information available
with the HTML form Method as to character set and language SHOULD be
used.
2.3 An ECML 1.1 XML DTD
Below is an XML DTD that can be used for the XML encoding of ECML
v1.1 Fields.
For internationalization of [XML] ECML, use the general XML character
encoding provisions, which mandate support of UTF-8 and UTF-16 and
permit support of other character sets, and the xml:lang attribute
which may be used to specify language information.
<!ELEMENT Ecom ( #PCDATA | ShipTo | BillTo | ReceiptTo | Payment |
User | Transaction | TransactionComplete )* >
<!ATTLIST Ecom
id ID #IMPLIED
ConsumerOrderID CDATA #IMPLIED
Merchant CDATA #IMPLIED
Processor CDATA #IMPLIED
SchemaVersion ( "http://www.ecml.org/version/1.0" |
"http://www.ecml.org/version/1.1" )
#IMPLIED
WalletID CDATA #IMPLIED >
<!ELEMENT ShipTo ( #PCDATA | Postal | Telecom | Online )* >
<!ATTLIST ShipTo
id ID #IMPLIED >
<!ELEMENT BillTo ( #PCDATA | Postal | Telecom | Online )* >
<!ATTLIST BillTo
id ID #IMPLIED >
<!ELEMENT ReceiptTo ( #PCDATA | Postal | Telecom | Online )* >
<!ATTLIST ReceiptTo
id ID #IMPLIED >
<!ELEMENT Postal ( #PCDATA | Name | Company |
Street | City | StateProv )* >
<!ATTLIST Postal
id ID #IMPLIED
PostalCode NMTOKEN #IMPLIED
CountryCode NMTOKEN #IMPLIED >
<!ELEMENT Name EMPTY >
<!ATTLIST Name
id ID #IMPLIED
Prefix NMTOKEN #IMPLIED
First NMTOKEN #IMPLIED
Middle NMTOKEN #IMPLIED
Last NMTOKEN #IMPLIED
Suffix NMTOKEN #IMPLIED >
<!ELEMENT Street EMPTY >
<!ATTLIST Street
id ID #IMPLIED
Line1 CDATA #REQUIRED
Line2 CDATA #IMPLIED
Line3 CDATA #IMPLIED >
<!ELEMENT Company #PCDATA >
<!ELEMENT City #PCDATA >
<!ELEMENT StateProv #PCDATA >
<!ELEMENT Telecom ( #PCDATA | Phone )* >
<!ELEMENT Phone EMPTY >
<!ATTLIST Phone
id ID #IMPLIED
Number CDATA #REQUIRED >
<!ELEMENT Online ( #PCDATA | Email )* >
<!ELEMENT Email EMPTY >
<!ATTLIST Email
id ID #IMPLIED
Address CDATA #REQUIRED >
<!ELEMENT Payment Card>
<!ELEMENT Card ExpDate >
<!ATTLIST Card
id ID #IMPLIED
Name CDATA #IMPLIED
Type NMTOKEN #IMPLIED
Number NMTOKEN #REQUIRED
Protocols NMTOKENS #IMPLIED
Verification NMTOKEN #IMPLIED >
<!ELEMENT ExpDate EMPTY >
<!ATTLIST ExpDate
id ID #IMPLIED
Day NMTOKEN #IMPLIED
Month NMTOKEN #REQUIRED
Year NMTOKEN #REQUIRED >
<!ELEMENT User ( #PCDATA | UserID | Password )* >
<!ATTLIST User
id ID #IMPLIED >
<!ELEMENT UserID #PCDATA >
<!ELEMENT Password #PCDATA >
<!ELEMENT Transaction ( #PCDATA | TransactionID | Inquiry |
TransDate | Signature )* >
<!ATTLIST Transaction
id ID #IMPLIED
Amount CDATA #IMPLIED
Currency NMTOKEN #IMPLIED
Type NMTOKEN #IMPLIED >
<!ELEMENT TransactionComplete EMPTY>
3. Using The Fields
To conform to this document, the field names must be structured and
named as close to the structure and naming listed in Section 2 above
as permitted by the transaction protocol in use. Note: this does not
impose any restriction on the user visible labeling of fields, just
on their names as used in communication.
3.1 Presentation of the Fields
There is no necessary implication as to the order or manner of
presentation. Some merchants may wish to ask for more information,
some less by omitting fields. Some merchants may ask for the
information they want in one interaction or web page, others may ask
for parts of the information at different times in multiple
interactions or different web pages. For example, it is common to
ask for "ship to" information earlier, so shipping cost can be
computed, before the payment method information. Some merchants may
require that all the information they request be provided while other
make much information optional. Etc.
There is no way with Version 1.0 or 1.1 of ECML to indicate what
fields the merchant considers mandatory. From the point of view of
customer software, all fields are optional to complete. However, the
merchant may give an error or re-present a request for information if
some field it requires is not completed, just as it may if a field is
completed in a manner it considers erroneous.
It is entirely up to the merchant when and which, if any, of the
merchant to consumer fields it presents.
3.2 Methods and Flow of Setting the Fields
There are a variety of methods of communication possible between the
customer and the merchant by which the merchant can indicate what
fields they want that the consumer can provide. Probably the easiest
to use for currently deployed software is as fields in an [HTML] form
(see section 2.2). Other possibilities are to use the IOTP
Authenticate transaction [RFC 2801], an [XML] exchange, or
proprietary protocols.
User action or the appearance of the Ecom_SchemaVersion field are
examples of triggers that could be used to initiate a facility
capable of filling in fields. Because some wallets may require user
activation, there should be at least one user visible Ecom field on
every page with any Ecom fields present that are to be filled in. It
is also REQUIRED that the Ecom_SchemaVersion field, which is usually
a hidden field, be included on every web page that has any Ecom
fields.
Because web pages can load very slowly, it may not be clear to an
automated field fill-in function when it is finished filling in
fields on a web page. For this reason, it is recommended that the
Ecom_SchemaVersion field be the last Ecom field on a web page.
Merchant requests for information can extend over several
interactions or web pages. Without further provision, a facility
could either require re-starting on each page or possibly violate or
appear to violate privacy by continuing to fill in fields for pages
beyond with end of the transaction with a particular merchant. For
this reason the Ecom_TransactionComplete field, which is normally
hidden, is provided. It is recommended that it appear on the last
interaction or web page involved in a transaction, just before an
Ecom_SchemaVersion field, so that multi-web-page automated field fill
in logic could know when to stop if it chooses to check for this
field.
4. Security and Privacy Considerations
The information called for by many of these fields is sensitive and
should be secured if being sent over the public Internet or through
other channels where it can be observed. Mechanisms for such
protection are not specified herein but channel encryption such as
TLS/SSL [RFC 2246] or IPSec [RFC 2411] would be appropriate in many
cases.
User control over release of such information is needed to protect
the user's privacy.
A wallet that is installed on a shared or public terminal should be
configurable such that the ECML memory of address and other contact
information is fully disabled. This is vital to protect the privacy
of library patrons, students, and customers using public terminals,
and children who might, for example, use a form on a public terminal
without realizing that their information is being stored.
When contact information is stored, the operator should have an
option to protect the information with a password, without which the
information might be unavailable, even to someone who has access to
the file(s) in which it is being stored. This would also allow for a
convenient method for multiple people to use their own ECML
information from the same browser.
Any multi-web-page or other multi-aggregate field fill in or data
provision mechanism should check for the Ecom_TransactionComplete
field and cease automated fill when it is encountered until fill is
further authorized.
References
[eCheck] http://www.echeck.org
[HTML] HTML 3.2 Reference Specification
http://www.w3.org/TR/REC-html32.html,
D. Raggett, January 1997.
[IANA] Internet Assigned Numbers Authority, Official Names for
Character Sets, ed. Keld Simonsen et al.
ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets.
[ISO 3166] Codes for the representation of names of countries,
http://www.din.de/gremien/nas/nabd/iso3166ma
[ISO 7812] "Identification card - Identification of issuers - Part 1:
Numbering system".
[RFC 1766] Alvestrand, H., "Tags for the Identification of
Languages", BCP 47, RFC 3066, January 2001.
[RFC 2026] Bradner, S., "The Internet Standards Process -- Revision
3", BCP 9, RFC 2026, October 1996.
[RFC 2246] Dierks, T. and C. Allen, "The TLS Protocol: Version 1.0",
RFC 2246, January 1999.
[RFC 2411] Thayer, R., Doraswany, N. and R. Glenn, "IP Security:
Document Roadmap", RFC 2411, November 1998.
[RFC 2706] Eastlake, D. and T. Goldstein, "ECML v1: Field Names for
E-Commerce", RFC 2706, September 1999.
[RFC 2801] Burdett, D., "Internet Open Trading Protocol - IOTP
Version 1.0", RFC 2801, April 2000.
[SET] Secure Electronic Transaction,
http://www.setco.org/set_specifications.html
[XML] Extensible Markup Language (XML) 1.0 (Second Edition),
http://www.w3.org/TR/REC-xml
T. Bray, J. Paoli, C. M.
Sperberg-McQueen, E. Maler.
Appendix: Changes from ECML 1.0
Authors' Addresses
Phone: +1-508-261-5434
Fax: +1-508-261-4447
EMail: Donald.Eastlake@motorola.com
Ted Goldstein
Brodia
221 Main Street, Suite 1530
San Francisco, CA 94105 USA
Phone: +1 415-495-3100 x222
Fax: +1 415-495-3177
EMail: tgoldstein@brodia.com
Full Copyright Statement
Copyright (C) The Internet Society (2001). All Rights Reserved.
based on : www.ietf.org/rfc/rfc3106.txt.
Rearanged by DG12
Copyright Notice
Copyright (C) The Internet Society (2001). All Rights Reserved.
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.
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
none, set,
setcert,
iotp,
echeck,
simcard, and
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.
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.
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.
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
<-- Electronic Commerce Modeling Language 1.1 -->
ECML 1.0 is documented in [RFC 2706].
Ecom_*_Postal_Company
Ecom_User_ID
Ecom_User_Password
Ecom_WalletID
Ecom_Merchant
Ecom_Processor
Ecom_Transaction_*
Donald E. Eastlake, 3rd
Motorola, M2-450
20 Cabot Boulevard
Mansfield, MA 02048
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.