payment instrument info

Author: stephenmcgruer

ux-guidelines.md

@@ -27,7 +27,7 @@ other entity) that the user has already been interacting with in the current
 session. The `payeeName` field, if present, communicates a natural language
 name, such as "Big Shoe Store Inc.", whilst the `payeeOrigin`, if present,
 communicates the web URL at which the payee can be found, such as
-`https://bigshoestore.example`.
+"https://bigshoestore.example".
 
 The specification allows for either one or both of the fields to be present.
 Implementors may display them separately, or may combine them into a single
@@ -42,12 +42,61 @@ length limits on fields including payeeName and payeeOrigin.
 
 Relevant fields: [instrument.displayName], [instrument.icon], [instrument.details]
 
+The payment instrument information fields are intended to communicate to the
+user which payment instrument will be charged. Common payment instruments
+include payment cards (credit, debit, or other), bank accounts, and a number of
+country-specific payment methods (e.g., UPI, PIX, GiroPay, etc). SPC has no
+requirement or limitation on the type of payment instrument being used or
+displayed.
+
+The `displayName` and `details` fields are used to convey textual information
+about the payment instrument. As the names suggest, `displayName` should be set
+to the primary name for the payment instrument, while `details` can be used to
+add additional clarifying details to help the user differentiate or make
+decisions.  For example, for a credit card payment instrument, `displayName`
+may be set to the product name for the card (e.g., "FancyBank Infinity Card"),
+whilst details might include the last four digits of the card and/or expiry
+date (e.g., "1234 01/32).
+
+Note: An implementor may truncate the `displayName` and `details` fields in
+order to fit the text into the available UX space. See issue #269 for
+discussions on setting normative length limits on fields including payeeName
+and payeeOrigin.
+
+The `icon` field is set to the URL of an image representing the payment
+instrument. Implementors are expected to support common image formats such as
+PNG or JPG. The payment instrument icon image is intended to be a quick visual
+confirmation for the user, and is expected to be displayed fairly small.
+
+Implementation specifics:
+
+- Google Chrome's (and other Chromium-based browsers) implementation on both
+  desktop and mobile platforms currently linearly scales the image (preserving
+  the input aspect ratio) to fit in a 32dp x 20dp region, e.g. the display
+  region has an aspect ratio of 1.6:1.
+    - Given current average screen densities, we would recommend that
+      integrators pass in a logo with physical pixel size at least 3x of that,
+      e.g. minimal 96px by 60px.
+    - The Chrome team have stated that they are interested in hearing from
+      partners if a 32dp x 20dp region is too small, as it may not allow for
+      detailed icons (such as full card art for credit cards).
+
 ### Payment entity logos
 
-Relevant fields: [paymentEntitiesLogos], [paymentEntitiesLogos\[x\].url], [paymentEntitiesLogos\[x\].label]
+Relevant fields: [paymentEntitiesLogos], [paymentEntitiesLogos\[x\].url], [paymentEntitiesLogos\[x\].label]a
+
+### Transaction amount
+
+Relevant fields: [details.total.amount.currency], [details.total.amount.value]
+
+Note: The transaction amount is communicated via the top-level [Payment
+Request](https://w3c.github.io/payment-request) API call, instead of as part of
+the SPC method itself.
 
 ## UX differences across different screen sizes/layouts
 
+## Appendix: Example transaction confirmation UX screens
+
 [instrument.details]: https://w3c.github.io/secure-payment-confirmation/#dom-paymentcredentialinstrument-details
 [instrument.displayName]:https://w3c.github.io/secure-payment-confirmation/#dom-paymentcredentialinstrument-displayname
 [instrument.icon]: https://w3c.github.io/secure-payment-confirmation/#dom-paymentcredentialinstrument-icon