Network Working Group D. Eastlake 3rd
Request for Comments: 4112 Motorola Laboratories
Updates: 3106 June 2005
Category: Standards Track
Electronic Commerce Modeling Language (ECML)
Version 2 Specification
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
Electronic commerce frequently requires a substantial exchange of
information in order to complete a purchase or other transaction,
especially the first time the parties communicate. A standard set of
hierarchically-organized payment-related information field names in
an XML syntax is defined so that this task can be more easily
automated. This is the second version of an Electronic Commerce
Modeling Language (ECML) and is intended to meet the requirements of
RFC 3505.
Table of Contents
1. Introduction ....................................................2
2. Field Definitions, DTD, and Schema ..............................3
2.1. Field List and Descriptions ................................3
2.1.1. The Field List ......................................4
2.1.2. Field Footnotes .....................................7
2.2. Exemplar XML Syntax .......................................12
2.2.1. ECML v2 XML DTD ....................................13
2.2.2. ECML v2 XML Schema .................................18
3. Usage Notes for ECML v2 ........................................26
3.1. Presentation of the Fields ................................26
3.2. Methods and Flow of Setting the Fields ....................27
4. Security and Privacy Considerations ............................28
5. IANA Considerations ............................................29
5.1. ECML v2 Schema Template ...................................29
5.2. ECML v2 URN Template ......................................29
5.2.1. Sub-registration of v2.0 ...........................30
5.3. IANA Registries ...........................................30
6. Acknowledgements ...............................................30
A. Appendix: Changes from v1.1 to v2 ..............................31
Normative References ..............................................31
Informative References ............................................32
1. Introduction
Numerous parties are conducting business on the Internet using ad hoc
fields and forms. The data formats and structure can vary
considerably from one party to another. Where forms are filled out
manually, some users find the diversity confusing, and the process of
manually filling in these forms can be tedious and error prone.
Software tools, including electronic wallets, can help this
situation. Such tools can assist in conducting online transactions
by storing billing, shipping, payment, preference, and similar
information and using this information to complete the data sets
required by interactions automatically. For example, software that
fills out forms has 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 more automated transaction software has been
hampered by the lack of standards.
ECML (Electronic Commerce Modeling Language) provides a set of
hierarchical payment-oriented data structures that will enable
automated software, including electronic wallets from multiple
vendors, to supply and query for needed data in a more uniform
manner.
Version 2.0 extends ECML Versions 1.0 [RFC2706] and 1.1 [RFC3106] as
described in the appendix to this document. These enhancements
include support for additional payment mechanisms and transaction
information and use of XML as the exemplar syntax.
ECML is designed to provide a simple baseline useful in a variety of
contexts. Likely uses for ECML v2 are consumer payment information
input and business-to-business transactions. At this time, the first
is still likely to occur through HTML forms. The second is more
likely to use XML documents.
1.2. History and Relationship to Other Standards
The ECML fields were initially derived from the W3C P3P base data
schema [P3P.BASE] by the ECML Alliance as described in [RFC2706,
RFC3106]. Technical development and change control of ECML was then
transferred to the IETF. In version 2, ECML is extended by the
fields in a W3C P3P Note related to eCommerce [P3P.ECOM], by
[ISO8583], and other sources. Its primary exemplar form is now an
XML syntax.
2. Field Definitions, DTD, and Schema
ECML v2 is the definition and naming of a hierarchically structured
set of fields and the provision of an optional XML syntax for their
transmission. These fields can be encoded in other syntaxes.
Regardless of the encoding used, the fields can be transmitted via a
variety of protocols.
Section 2.1 below lists and describes the fields, Section 2.2.1
provides an XML DTD for use with the fields, and Section 2.2.2
provides an XML schema.
To conform to this document, field names must be named and
hierarchically structured as closely to the structure and naming
listed below as is practical given the syntax and transaction
protocol in use. (NOTE: This does not impose any restriction on
human visible labeling of fields, just on their name or names and
structure as used in on-the-wire communication.)
2.1. Field List and Descriptions
The fields are listed below, along with the minimum data entry size
allowed. Implementations may accept larger data sizes, if doing so
makes sense, and, for some applications, they will need to allow for
larger data sizes.
Note that these fields are hierarchically organized as indicated in
this table 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 of a
set of card expiry date components) or Ecom_ShipTo (to encompass all
the ship-to address components that a consumer is willing to
provide). The labeling, marshalling, and unmarshalling of the
components of such aggregates depend on the data transfer protocol
used. The suggested syntax is XML as specified in Section 2.2.
2.1.1. The Field List
The table below is the ECML v2 field list.
The NAME column gives the structured string name of each field as
explained above. The MIN column below is the minimum data size that
MUST be allowed for on data entry. It is NOT the minimum size for
valid contents of the field, and merchant software should, in many
cases, be prepared to receive a longer or shorter value. Merchants
dealing with areas where, for example, the state/province name or
phone number is longer than the MIN given below obviously must permit
longer data entry. In some cases, however, there is a maximum size
that makes sense, and where this is the case, it is usually
documented in a Note for the field.
The following fields are typically 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 (54)
ship to middle name Ecom_ShipTo_Postal_Name_Middle 15 ( 2)
ship to last name Ecom_ShipTo_Postal_Name_Last 15 (54)
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 (54)
bill to middle name Ecom_BillTo_Postal_Name_Middle 15 ( 2)
bill to last name Ecom_BillTo_Postal_Name_Last 15 (54)
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)
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 (54)
receipt to middle name Ecom_ReceiptTo_Postal_Name_Middle 15 ( 2)
receipt to last name Ecom_ReceiptTo_Postal_Name_Last 15 (54)
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 issuer number Ecom_Payment_Card_IssueNumber 2 (53)
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 valid date day Ecom_Payment_Card_ValidFrom_Day 2 (14)
card valid date month Ecom_Payment_Card_ValidFrom_Month 2 (15)
card valid date year Ecom_Payment_Card_ValidFrom_Year 4 (16)
card protocols Ecom_Payment_Card_Protocol 20 (17)
loyalty card name Ecom_Loyalty_Card_Name 30 (10)
loyalty card type Ecom_Loyalty_Card_Type 20 (52)
loyalty card number Ecom_Loyalty_Card_Number 40 (34)
loyalty card verification Ecom_Loyalty_Card_Verification 4 (13)
loyalty card expire day Ecom_Loyalty_Card_ExpDate_Day 2 (14)
loyalty card expire month Ecom_Loyalty_Card_ExpDate_Month 2 (15)
loyalty card expire year Ecom_Loyalty_Card_ExpDate_Year 2 (16)
loyalty card valid day Ecom_Loyalty_Card_ValidFrom_Day 2 (14)
loyalty card valid month Ecom_Loyalty_Card_ValidFrom_Month 2 (15)
loyalty card valid year Ecom_Loyalty_Card_ValidFrom_Year 4 (16)
consumer order ID Ecom_ConsumerOrderID 20 (18)
user ID Ecom_User_ID 40 (19)
user password Ecom_User_Password 20 (19)
user certificate Ecom_User_Certificate_URL 128 (55)
user data country Ecom_UserData_Country 2 ( 7)
user data language Ecom_UserData_Language 30 (33)
user data gender Ecom_UserData_Gender 1 (36)
user data birth day Ecom_UserData_BirthDate_Day 2 (14)
user data birth month Ecom_UserData_BirthDate_Month 2 (15)
user data birth year Ecom_UserData_BirthDate_Year 4 (16)
user data preferences Ecom_UserData_Preferences 60 (34)
schema version Ecom_SchemaVersion 30 (20)
wallet id Ecom_WalletID 40 (21)
wallet URL Ecom_Wallet_Location 128 (35)
customer device ID Ecom_Device_ID 20 (37)
customer device type Ecom_Device_Type 20 (38)
end transaction flag Ecom_TransactionComplete - (22)
The following fields are typically 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 24 (30)
transaction signature Ecom_Transaction_Signature 160 (31)
end transaction flag Ecom_TransactionComplete - (22)
The following fields are used to communicate between the merchant and
a processor acting for the merchant (such a processor is commonly
called an acquirer and is frequently a bank):
FIELD NAME Min Notes
merchant identifier Ecom_Merchant_ID 8
merchant terminal Ecom_Merchant_Terminal_ID 8 (39)
merchant terminal data Ecom_Merchant_Terminal_Data 128
transaction process code Ecom_Transaction_ProcessingCode 6 (40)
transaction reference Ecom_Transaction_Reference_ID 12
transaction acquirer Ecom_Transaction_Acquire_ID 13 (41)
transaction forward Ecom_Transaction_Forward_ID 13 (42)
transaction trace Ecom_Transaction_Trace_Audit 6 (43)
transaction effective date Ecom_Transaction_Effective_Date 4 (44)
transaction CID Ecom_Transaction_CID 8
transaction POS Ecom_Transaction_POSCode 12 (45)
transaction private use Ecom_Transaction_PrivateUseData 166
transaction response Ecom_Transaction_ResponseData 27
transaction approval code Ecom_Transaction_ApprovalCode 12 (46)
transaction retrieval code Ecom_Transaction_RetrievalCode 128
transaction response action Ecom_Transaction_ActionCode 13 (47)
transaction reason Ecom_Transaction_ReasonCode 4
transaction AAV Ecom_Transaction_AAV 3
transaction settlement date Ecom_Transaction_Settle_Date 4 (48)
transaction capture date Ecom_Transaction_Capture_Date 4 (49)
transaction Track 1 Ecom_Transaction_Track1 39 (50)
transaction Track 2 Ecom_Transaction_Track2 39 (51)
2.1.2. Field Footnotes
(1) For example: Mr., Mrs., Ms., Dr. This field is commonly
omitted.
(2) May also be used for middle initial.
(3) For example: Ph.D., Jr. (Junior), 3rd, Esq. (Esquire). This
field is commonly omitted.
(4) Address lines must be filled in the order line1, then line2, and
last line3. Thus, for example, it is an error for line1 to be
null if line2 or line3 is not.
(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 according to the
international market served. Use 5-character postal code 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 [ISO3166] standard two letter country codes.
(8) 10 digits are the minimum for numbers within the North American
Numbering Plan (<http://www.nanpa.com>: It includes the US,
Canada and a number of Caribbean and smaller 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, etc. Although it is desirable for telephone numbers
to be in standard international format [E.164], it may be
necessary to use heuristics or human examination based on the
telephone number and addresses given to figure out how to call a
customer, since people may enter local formatted numbers without
area/access codes. It is recommend that an "x" be placed before
extension numbers and that the "x" and extension number appear
after all other parts of the number.
(9) For example: jsmith@example.com
(10) The name of the cardholder as it appears on the card.
(11) Case insensitive. Use up to the first 4 letters of the
association name (see also Note 102):
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 the end but no spaces or hyphens
[ISO7812]. 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
the American Express CIV, MasterCard CVC2, and Visa 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. The following is the initial list of case-
insensitive tokens:
none
set
setcert
iotp
echeck
simcard
phoneid
"Set" indicates that the card is usable with SET protocol (i.e.,
it is in a SET wallet) but that it does not have a SET
certificate [SET]. "Setcert" indicates that the card is usable
with SET and has a set certificate [SET]. "iotp" indicates that
the IOTP protocol [RFC2801] is supported at the customer.
"echeck" indicates that the eCheck protocol [eCheck] is
supported at the customer. "simcard" indicates an ability to