Electronic Commerce Modeling Language (ECML) Version 2 Specification
updates
- rfc-3106 — ECML v1.1: Field Specifications for E-Commerce
Extracted elements (31)
ECML v2 adopts XML as the exemplar syntax but deliberately keeps the XML syntax liberal, deferring additional constraints to specific applications, because the standard is intended as a simple baseline for diverse contexts including HTML forms and B2B XML documents.
Hierarchical field organization is expressed using embedded underscore characters in flat field names (e.g., Ecom_ShipTo_Postal_City) so that both flat key-value encodings and XML aggregates can represent the same structure, enabling use across HTML forms, XML, and proprietary protocols.
The ReceiptTo group of fields is included because for some corporate purchasing card scenarios the individual cardholder (ReceiptTo) differs from the corporate billing entity (BillTo); without this separation, the distinction could not be expressed.
The field names 'first_name' and 'last_name' are retained from ECML v1.x for compatibility, but 'last_name' should be understood as family/inherited name(s) and 'first_name' as the first given name, diverging from the literal English interpretation.
The XML Schema in Section 2.2.2 takes precedence over the DTD in Section 2.2.1 in case of conflict; both are provided but applications should validate against the Schema.
Any multi-page or multi-aggregate field fill-in mechanism SHOULD check for the Ecom_TransactionComplete field and cease automated fill when it is encountered until further authorized.
Ecom_SchemaVersion SHOULD appear on every web page that has any Ecom fields; it is RECOMMENDED that it be the last Ecom field on each web page so automated processing can detect when field reception is complete.
Field names MUST be named and hierarchically structured as closely to the structure and naming in Section 2.1 as is practical given the syntax and transaction protocol in use. This constraint applies to on-the-wire names, not to human-visible labeling.
It is RECOMMENDED that Ecom_TransactionComplete appear on the last interaction or web page of a transaction, just before the Ecom_SchemaVersion field, to signal multi-interaction automated logic when to stop.
It is RECOMMENDED that there be at least one user-visible Ecom field on every web page containing any Ecom fields when ECML is used via the web, because some web software may require user activation to trigger autofill.
It is REQUIRED that the Ecom_SchemaVersion field be included in every transaction when ECML is being used on the web, so that browser software can identify the version in use.
Query elements may carry data content; such content SHOULD be interpreted as a default value to be returned if no better value is known.
The minimum data entry size specified in the MIN column MUST be allowed for each field. Implementations may accept larger data sizes; this is not a minimum for valid field contents.
Software installed on shared or public terminals must be configurable to fully disable memory of any sensitive or individual identity information, to protect library patrons, students, and children who may use public terminals without realizing their data is being stored.
When sensitive or individual identification information is stored, the operator or user should have an option to protect it with a password so that the data is unavailable even to someone with file-system access.
Ecom_Payment_Card_Protocol holds a space-separated list of case-insensitive protocol tokens (none, set, setcert, iotp, echeck, simcard, phoneid) indicating payment capabilities associated with the card.
Ecom_TransactionComplete is an empty flag field (no MIN) that signals the end of a multi-page transaction; it is normally a hidden HTML form field and appears on the last page just before Ecom_SchemaVersion.
Ecom_User_Certificate_URL (min 128) holds a URI pointing to the user's X.509v3 certificate encoded as binary DER; Ecom_Transaction_Signature (min 160) carries a base64-encoded digital signature of the transaction.
Merchant-to-processor fields (Section 2.1.1 third table) map directly to ISO 8583 fields including processing code, acquiring/forwarding institution IDs, system trace audit, approval code, action code, Track 1/Track 2 data, and settlement/capture dates.
Payment card fields include Ecom_Payment_Card_Name (min 30), Ecom_Payment_Card_Type (min 4, case-insensitive, 1-4 letter code), Ecom_Payment_Card_Number (min 19, ISO 7812 check digit included, no spaces or hyphens), Ecom_Payment_Card_Verification (min 4, CVV/CVC2/CIV), and expiry/valid-from date components.
The Mode attribute (values: Query or Assert) may be applied to any element and propagates to all descendant elements until overridden, allowing an entire ECML structure to be flagged as a request for information or a provision of it.
The root Ecom XML element carries optional attributes ConsumerOrderID, Merchant, Mode (Query|Assert), Processor, SchemaVersion (fixed to 'urn:ietf:params:ecml:v2.0'), WalletID, and WalletLocation, and may contain ShipTo, BillTo, ReceiptTo, Payment, Loyalty, User, Merchant, Transaction, and TransactionComplete child elements.
IANA registry Ecom_Payment_Card_Protocol: case-insensitive alphanumeric ASCII tokens for payment protocols usable with a card (initial 7 values: none, set, setcert, iotp, echeck, simcard, phoneid); new entries require expert approval.
IANA registry Ecom_Payment_Card_Type: case-insensitive alphanumeric ASCII tokens of 1–4 characters identifying payment card associations (initial 12 values include VISA, MAST, AMER, DISC, etc.); new entries require expert approval and normally an existing ISO IIN.
IANA registry Ecom_Transaction_Type: case-insensitive alphabetic ASCII values for transaction type (initial values: debit, credit); new entries require expert approval.
The URN sub-namespace urn:ietf:params:ecml is permanently registered per RFC 3553; subordinate values are registered by RFC publication and, once registered, may never change. The sub-value 'v2.0' is registered by this document to identify ECML v2.0-conformant fields.
Default, hidden, and other field values transferred to another party may be maliciously modified before being returned; implementations must not blindly trust such values.
ECML fields contain sensitive information that must be protected from unauthorized modification and kept confidential; appropriate mechanisms include object security (XMLDSIG, XML encryption, CMS) or channel security (TLS, IPsec). Systems that store and forward ECML data will typically find object security most appropriate.
Card number field (Ecom_Payment_Card_Number) encodes the ISO 7812 account number including the check digit, with no embedded spaces or hyphens; maximum length is 19 characters under the ISO standard.
ECML v2 provides both an XML DTD (Section 2.2.1) and an XML Schema (Section 2.2.2) as its exemplar syntax; in case of conflict between them, the Schema prevails. Fields may also be encoded in non-XML syntaxes.
Ecom_SchemaVersion carries the URI 'urn:ietf:params:ecml:v2.0' for this version; the XML Schema fixes the SchemaVersion attribute to this value. Country codes use ISO 3166-1 two-letter codes; currency codes use ISO 4217 three-letter codes; transaction amounts use ISO 4217 numeric format (two integers separated by a period, no currency symbol).