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.
AbstractCustomers 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.
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 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
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, <www.ecml.org>) 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.
13. Sun Microsystems (www.sun.com) 14. Trintech (www.trintech.com> 15. Visa International (www.visa.com) 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. 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.
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.
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)
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.
( 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 <http://www.din.de/gremien/nas/nabd/iso3166ma/index.html> for country names. ( 8) 10 digits are the minimum for numbers local to the North American Numbering Plan (<http://www.nanpa.com>: 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: email@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.
(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.
(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. 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.
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. <!-- Electronic Commerce Modeling Language 1.1 --> <!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> 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.
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.
<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> </BODY> </HTML> After all of the pages are submitted, the merchant will reply with a confirmation page informing both the user and the wallet that the transaction is complete. <HTML> <HEAD> <title> eCom Transaction Complete Example </title> </HEAD> <BODY> <FORM> Thank you for your order. It will be shipped in several days. <INPUT type="hidden" name="Ecom_Merchant" value="www.merchant.example"> <INPUT type="hidden" name ="Ecom_Processor" value="www.processor.example"> <INPUT type="hidden" name="Ecom_Transaction_ID" value="EF123456"> <INPUT type="hidden" name="Ecom_Transaction_Inquiry" value="http://www.merchant.example/cgi-bin/inquire?ID=EF123456"> <INPUT type="hidden" name="Ecom_Transaction_Amount" value="789.00"> <INPUT type="hidden" name="Ecom_Transaction_Currency" value="USD"> <INPUT type="hidden" name="Ecom_Transaction_Date" value="July 14 2000"> <INPUT type="hidden" name="Ecom_Transaction_Type" value="credit"> <INPUT type="hidden" name="Ecom_Transaction_Signature" value="ig6rh4;;20dfna00s34hj10s--s-45j30-22z92l-frwds-85"> <INPUT type="hidden" name="Ecom_TransactionComplete"> <INPUT type="hidden" name="Ecom_SchemaVersion" value="http://www.ecml.org/version/1.1"> </FORM> </BODY> </HTML>
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. [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.
RFC 2706]. (1) Fields added for consumer to merchant transmission as listed below. * indicated multiple values. Adding fields is a backward compatible change. Ecom_*_Postal_Company Ecom_User_ID Ecom_User_Password Ecom_WalletID (2) Change Ecom_SchemaVersion field value to "http://www.ecml.org/version/1.1". (3) Addition of XML DTD. (4) Add "iotp", "echeck", "simcard", and "phoneid" as allowed tokens in Ecom_Payment_Card_Protocol. (5) Specify that a leading zero is permitted in day and month number fields. (6) Change "Security Considerations" section to "Security and Privacy Considerations" and add material. (7) Add internationalization material to HTML and XML subsections of Section 2. (8) Enumerate HTML form elements that must be supported (Section 2.2) including SELECT. (9) Add more credit card brand codes. (10) Add fields for merchant to consumer transmissions as follows: Ecom_Merchant Ecom_Processor Ecom_Transaction_*
Full Copyright Statement Copyright (C) The Internet Society (2001). All Rights Reserved. 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.