w3c / webpayments

The document repo for the Web Payments Working Group

webpayments

This is the primary repository for the Web Payments Working Group. Please see our wiki for links to documents and specific document repositories, and proposals not yet taken up by the Working Group

webpayments's Issues

Should the payment request contain line item details?

The paymentRequest API currently includes a Payment Details object in a payment request:

http://wicg.github.io/paymentrequest/specs/paymentrequest.html#paymentdetails-dictionary
http://wicg.github.io/paymentrequest/specs/paymentrequest.html#paymentrequest-interface

The Web Payments CG's Browser API specifically does not provide such an interface because small and large retailers have stated that they do not want that information forwarded on to payment service processors (they don't want large technology companies mining their customer data).

What is the expected use case for the payment details object?

Capture proposed work changes in wiki

What is the appropriate conversational pattern for the API?

i.e. Should the API be an open channel for communication between the Website and Payment App or should it simply accept a request and return a response and all other comms must be done out of band?

This question has been raised implicitly in a few other issues such as #41 and #39.

It is also surfaced as a requirement of the API due to the discussion around shipping, tax and line item details.

In the case of the browser API the options are:

Option 1
The API accepts a payment request and focus moves to the Payment App. The Payment App will return a payment response to the Website and the Payment App will close.

navigator.payments.requestPayment(...)
.then(function(paymentResponse){
  //Process the payment
});

Pros

• Simple API. All data is passed in a single request
• Simple state flow. The Website passes control to the API (and therefor the Payment App gets focus) and when it get's back a response it is able to process it. No need to track state or listen for events.
  • Loose coupling. A simple request/response flow means the coupling between the Website and Payment App is loosely defined.
  • Simple UX. The user experiences a single focus change as the Payment App is brought into focus and then closed when their interaction completes.

Cons

• Inflexible. All possible pricing options for all supported payment methods must be included in the request which means the request grows exponentially with each new option or variation of the offer.
• Static. It's impossible to adjust the offer/request based upon the user's input such as shipping address, loyalty club membership, coupon code etc.

Option 2
The API accepts a payment request and focus moves to the Payment App. Certain actions in the Payment App will cause a message to be returned to the Website during which time the Payment App UI will remain in focus but will be in a non-responsive or waiting state until the Website responds to that message and the Payment App can continue processing based on the Website's response. Finally the Payment App will return a payment response to the Website and the Payment App will close.

navigator.payments.addEventListener("paymentAppMessage", function (msg) {
  //Process msg and update payementRequest
  navigator.payments.updatePaymentRequest(...);
});

navigator.payments.requestPayment(...)
.then(function(paymentResponse){
  //Process the payment
});

Pros

• Infinitely flexible. Websites can develop innovative offers with dynamic pricing and complex interactions with Payment Apps
• Smaller messages. The initial request can be much simpler.

Cons

• UX complexity. Either the focus continuously switches between the Payment App and the Website (terrible UX) or the Payment App (while in focus) becomes unresponsive and enters a wait/loading state while waiting for the Website to respond to a message.
• Asynchronous API with synchronous messaging. The Website and Payment App send messages asynchronously however the behavior of the two components is very dependent on the content of the responses they get so the processing they can do in parallel is very limited.

How should the message schemas for the payment request and response be defined? What is the extensibility story for the messages?

To accept a payment method, a merchant must know how to process the response from the Payment Request API. Should there be a base universal response format? If so, some payment instruments may need more information in the returned message to figure out if the payment was successful, how is this other information placed in there?

This is related to issue #25, Payment Method Identifier Registry.

Spec refs:
http://wicg.github.io/paymentrequest/specs/architecture.html#payment-request-api
http://web-payments.github.io/web-payments-messaging/#payment-instrument-registration

Please enable issues to be reflected on the mailing list

Issues are currently not reflected on the mailing list. Please enable that feature.

How can the API support enrollment (future payment) use cases?

Migrated from https://github.com/WICG/paymentrequest/issues/43

@ianbjacobs:

Here is a use case that should be supported:

• Service asks user at enrollment to register payment details for future use
• API is used to retrieve those details, but no payment should actually take place.

Some payment apps might support this (e.g., raw credit card information) while others might not
(e.g., those that return 1-time tokens).

What (if anything) does the API need to say to help readers recognize that it supports this
enrollment use case?

For example, suppose the preferred way to use the API for enrollment to specify amount=0.
The spec should say something to that effect and, for example, ensure that the definition of
amount supports that value.

Or, there might be other ways the API could support the enrollment use case. I look forward to
your thoughts.

@adrianba:

There may be many occasions where a site wants to request a payment method but not to make a charge. For example, it is common to provide a credit card number to book a car rental or to make a hotel reservation but the payment is made later, in person, and potentially with a different payment method. The merchant may charge the original payment method under some circumstances (for example no show at the hotel).

This seems very payment method specific. Perhaps we need to explore the "amount=0" use case?

@mattsaxon:

There are 2 sub uses cases to consider here;

1. An identification validation, amount=0 might be a reasonable approach here
2. A deposit/reserve, e.g. a hotel deposit, a common way of doing this to authorise an actual amount, but not make the charge unless something happens, this is known as an "authorisation" without a "capture", effectively these are two seperate transactions when can be bundled as a "sale". The flows we have documented so far don't differentiate these as the distinction occurs between the merchant and the merchant PSP, not between the shopper and the merchant. However it might be prudent to have a distinction in the target model so the user is aware what they are signing up to.

Should a Payment Request API have shipping address APIs?

The current paymentRequest API has specific facilities for gathering shipping address information:

http://wicg.github.io/paymentrequest/specs/paymentrequest.html#paymentrequest-interface

    readonly attribute ShippingAddress? shippingAddress;
    readonly attribute DOMString? shippingOption;
    attribute EventHandler        onshippingaddresschange;
    attribute EventHandler        onshippingoptionchange;

The Web Payments CG's Browser API spec delegates this functionality to the Credential Management API (aka/or Verifiable Claims API).

Should the payment request API have shipping address APIs?

Should we be concerned about the use of the Browser API in a non-HTTPS environment?

Should the Browser API be restricted to HTTPS-only environments?

Payment Method Identifier Registry should have oversight / formal structure

The Payment Request Architecture diagram specifies a Payment Method Identifier Registry and suggests that it may be a wiki. Who has write access to that wiki and what is the structure of that wiki?

I suggest that instead of a wiki, we use a document that is controlled by the Web Payments IG. The process for getting something into that document doesn't need to be complex (as simple as a pull request or an email to the group), but ultimately, entries into that document should be discussed.

For example, there are 669 cryptocurrencies, do all of them get to update their entries in the registry? Is the registry open to all?

I suggest we use URLs to identify payment types. Then we make the registry necessary ONLY if you want a short-name like "Visa" or "MasterCard", or you want to document how you are compatible with the Web Payments standard (standardized request format and response format).

The other thing we want to ensure is that there is some discussion upon the integration of a new payment method (actual standardization discussion, not just one person coming in and slapping their idea on a page). To be clear, none of this should prevent anyone from launching their own payment method. The registry is an optimization and information repository and is not required for new participants to enter the ecosystem.

I propose that, at a minimum, the following data is in each entry in the registry:

• payment method URL (the identifier)
• shortcode (like "Visa", "Bitcoin", etc.)
• payment request format
• payment response format

I propose that the best format for this document is as a Linked Data Vocabulary with a corresponding JSON-LD context as that formalizes how the data is expressed and represented across different syntaxes.

Spec refs:
http://web-payments.github.io/web-payments-messaging/#payment-instrument-registration
http://web-payments.github.io/web-payments-messaging/#payment-request
http://web-payments.github.io/web-payments-messaging/#payment-acknowledgement
http://wicg.github.io/web-payments-browser-api/#payment-instrument-registration
http://wicg.github.io/paymentrequest/specs/architecture.html#payment-method-registration-specifications
http://wicg.github.io/paymentrequest/specs/method-identifiers.html#issue-1
http://wicg.github.io/paymentrequest/specs/method-identifiers.html#issue-2

Should Payment Method Identifiers and Messages be expressed using a Linked Data Vocabulary?

The Payment Method Identifiers spec states:

The PaymentRequest API requires that merchants supply a list identifiers for supported payment methods. This document defines those identifier strings and how they are created.

The Payment Request Architecture spec states:

we expect some message definitions to be shared amongst different payment apps.

The two sets of spec proposals agree that:

• There should be a list of identifiers for payment methods.
• There should be shared attributes across payment apps and methods.
• There should be short names for payment methods.
• We should support distributed extensibility.

This sounds an awful lot like a Linked Data vocabulary. Is it?

This is related to #25 Payment Method Identifier Registry.

Spec refs:
http://wicg.github.io/paymentrequest/specs/method-identifiers.html#introduction
http://web-payments.github.io/web-payments-messaging/#payment-instrument-registration

Should we expose status change events in the browser API?

The paymentRequest API exposes a number of events that a payee site may listen to while the payment request is being processed:

http://wicg.github.io/paymentrequest/specs/paymentrequest.html#events

The Web Payments CG Browser API specification does not expose any such events.

Are there use cases where listening to payment request processing events are useful to the payee's software?

PROPOSAL: Adopt ISO20022 terminology for payer and payee and use synonyms as appropriate

This proposal is an attempt to resolve the question raised in #59.

PROPOSAL:

In keeping with the WG resolution to try and root our terminology in the ISO20022 data dictionary the WG will adopt the following terms for use in its deliverables:

• Creditor [Merchant/Payee]
• Creditor Agent [Merchant/Payee's Payment Service Provider(PSP)]
• Debtor [Shopper/Payer]
• Debtor Agent [Shopper/Payer's Payment Service Provider(PSP)]

The WG will supplement these terms with appropriate synonyms as appropriate in order to provide clarity of meaning for the target audience.

Examples:

• "The merchant (creditor) website might store the ..."_
• "The buyer (debtor) will register a payment app issued by their bank (debtor agent) ..."_

Should the payment request support multiple pricing options?

Originally raised in the comments at https://github.com/WICG/paymentrequest/issues/41#issuecomment-178356991

There a number of reasons why a payment request may carry multiple pricing options:

1. The payee wants to explicitly accept payment in multiple currencies (USD and XBT for example)
2. The payee wants to offer different prices depending on which payment method is used.
3. The payee wants to offer multi-tender payments
4. The payee wants to offer discounted pricing under special circumstances (loyalty, coupons etc)

These use cases could be addressed in different ways:

• A protocol like the Interledger Protocol would make matching the currency of the payer and payee unnecessary as the protocol would allow the payee to receive payment in the currency of their choice even if the payer pays using a different asset. The same could be said for many card based payments where currency conversion is handled by the network. i.e. For some use cases the payee simply provides a price and the payment app takes responsibility for making the payment at that price and in that currency.
• Each payment method could specify a price, or there could be a base price and any methods with a variation on that price would specify their unique price.
• The payment request can specify a guide price and the payment app can request updated pricing from the payee based on user input (coupon, currency selection, loyalty program login etc). This is related to the question at #76

Should a payment method identifier (URL) resolve to a machine readable resource that describes the payment method?

The Payment Method Identifiers asks:

If the payment method identifier is a URL, should there be a resource that can be fetched from the URL? Is there a need to describe the payment method at the URL or provide some other information?

How are cloud-based payment apps supported?

In phase I, how do we support cloud-based payment instruments? These instruments require a user to:

1. Start on the merchant website
2. Click buy
3. Select the cloud-based instrument
4. Navigate to a 3rd party website to approve the transaction
5. Return to the merchant website with a token, approval code, or other proof that the transaction has been approved.

Terminology for payer/payee, user/merchant, debtor/creditor

The flows task force have been working on defining a normalized set of terminology for the flows and have identified a particular set of terms that require normalization.

To date the WG has used the terms payer and payee to identify the sending and receiving parties in a payment respectively. Many discussions and documents use the terms user and merchant as these are the most common specializations of these roles however the ISO20022 terms are debtor and creditor.

Document relationship diagrams?

I like the document diagram in the Payment Request Architecture document. This diagram should probably go in the capabilities document as the capabilities document is supposed to tie everything together across IGs/WGs.

Spec refs:
http://wicg.github.io/paymentrequest/specs/architecture.html#architecture
http://wicg.github.io/web-payments-browser-api/#how-this-document-is-organized

Expression of monetary amounts

The paymentRequest API currently suggests that we express monetary amounts using a mantissa and exponent:

http://wicg.github.io/paymentrequest/specs/paymentrequest.html#currencyamount

"amount": { "currencyCode": "USD", "mantissa": 5500, "exponent": 2 }, // US$55.00

The Web Payments CG Browser API suggests that we use strings for the amounts with a currency code:

http://wicg.github.io/web-payments-browser-api/#processing-a-payment-request

transfer: {
  amount: '4.35',
  currency: 'USD'
},

How should monetary amounts be expressed in the API?

Is tracking payment request state necessary?

The paymentRequest API tracks the payment request state:

http://wicg.github.io/paymentrequest/specs/paymentrequest.html#paymentrequest-interface

enum PaymentRequestState {
    "created",
    "interactive",
    "delegated",
    "accepted",
    "closed"
};

The Web Payments CG Browser API proposal does not:

http://wicg.github.io/web-payments-browser-api/#processing-a-payment-request

Should we report payment request state back to the payee and enable the payee site to react as the payer proceeds through the payment flow? Or should we avoid exposing this level of detail in an effort to reduce the cognitive overhead for the developers (simpler API) and implementation complexity for the API (easier to implement for browser manufacturers)? In short, what are the use cases for reporting the payment request state back to the payee?

PROPOSAL: The PaymentRequest object SHOULD NOT expose internal state information to the developer. Any design that requires developers to manage or understand the request state is a compromise in the API design that should be avoided where possible.

Proposed by @msporny
Related to the discussion in #36 and #41

XMLHttpRequest is a problematic API partially due to the fact that it stores state (like the PaymentRequest API proposal) and managing that state machine has led to developer code being brittle (due to race conditions when the state machine transitions from one state to the next).

It is possible (and beneficial) to build a Web Payments Browser API that doesn't expose any state information to the developer, and thus eliminates one source of race conditions and complex code flow management: http://wicg.github.io/web-payments-browser-api/#processing-a-payment-request

PROPOSAL: The PaymentRequest object MUST NOT expose internal state information to the developer.

No proprietary binary files, please

Hey @mattsaxon,

Thanks for putting the first set of flow diagrams together.

Three requests:

1. Let's not check in binary files that can easily be generated.
2. I don't know if checking in .docx files really helps us (because we can't include those in ReSpec and viewing them in the browser is problematic). My preference would be to commit SVGs or PNGs (if we absolutely have to commit something), with the preference being for SVGs (we can include SVGs in the ReSpec specs).
3. Finally, and this one is really pedantic, but can we not put spaces in directory names or file names. Many of us jump around in the command line and hack URLs to specify these directory locations and spaces frustrate some of the things we do (like having to type in %20 when specifying a directory location instead of just using a - character or a bi-capitalized character).

Abstract payment architecture

This issue is being created to track the abstract payment architecture wiki pages outlined here:

https://github.com/w3c/webpayments/wiki/A-Payments-Initiation-Architecture-for-the-Web
https://github.com/w3c/webpayments/wiki/Components

Should we be publishing a specification for an HTTP API?

Should we create a message flow for non-browser, HTTP-only clients?

Confining the definition of user agents to browsers

The Web Payments WG charter currently states that we're to work on deliverables for "user agents":

http://www.w3.org/Payments/WG/charter-201510.html#deliverables

It is clear that one of these user agents is a browser and the payment request work strongly binds to that concept by pulling in requirements like HTML5, DOM4, and ECMA-262 6th Edition:

http://wicg.github.io/paymentrequest/specs/paymentrequest.html#dependencies

There are many other types of user agents than just browsers. It could be argued that we're not fulfilling our charter if we deliver only the interfaces as defined in paymentRequest. To put this another way, if the charter stated that the WG is confined to just 'browsers', I expect that there would have been multiple formal objections to the charter.

I'm asserting that we need to consider an API that works for user agents that are not browsers (and instead demonstrate bindings to something more common across user agents like an HTTP API):

http://web-payments.github.io/web-payments-http-api/

This is not to say that we shouldn't also have APIs for browsers, but browsers are not the only deployment targets here. Is an HTTP API in scope for this WG?

Should list of accepted payment methods be strings or objects?

The paymentRequest API asserts that the list of accepted payment methods that a payee exposes to the payer should be a list of strings:

http://wicg.github.io/paymentrequest/specs/paymentrequest.html#paymentrequest-interface

For example:

["visa", "bitcoin", "bobpay.com"]

The Web Payments CG Browser API asserts that the list should be composed of objects:

http://wicg.github.io/web-payments-browser-api/#processing-a-payment-request

For example:

acceptedScheme: [{
    scheme: [
      'https://w3id.org/payment-schemes#Visa',
      'https://w3id.org/payment-schemes#Mastercard',
      'https://w3id.org/payment-schemes#Discover'
    ],
    transfer: {
      amount: '4.35',
      currency: 'USD'
    },
    paymentRequestService: 'https://merchant-psp.example.com/services/getPaymentInfo'
  }, {
    scheme: 'https://w3id.org/payment-schemes#Bitcoin',
    transfer: {
      amount: '0.0177',
      currency: 'BTC'
    },
    destination: '3QJmV3qfvL9SuYo34YihAf3sRCW3qSinyC'
  },

Should list of accepted payment methods be strings or objects?

Merge Payment Request Architecture with Capabilities Document

From the Payment Request Architecture document:

The Payment Request architecture is designed to separate different concerns of the Payment Request system into different specifications so that they can be discussed and moved forward independently. This document describes the architecture and explains what different specifications may be created and how the relate to each other. [link]

It feels like the Payment Request Architecture and the Web Payments IG's Capabilities document overlap (based on the desired goals for the capabilities document). I agree that we need a document like the Payment Request Architecture, but think that it should be placed into the architecture document (capabilities) the WPIG agreed upon.

Spec refs:
http://wicg.github.io/paymentrequest/specs/architecture.html#abstract

PROPOSAL: Pass the list of supported payment methods and the method-specific data in a single object

From the discussion at #37

The payment request will contain (among other things)

1. A set of supported payment methods
2. Optional request data that is specific to one or more payment methods

An efficient way to pass this data in the payment request is to use an array of objects, each containing important request data and each indicating which payment method the data applies to.

An example would like this:

[
  {
    "methods" : ["bobspay.com", "visa+tokenized", "visa+legacy", "mastercard"],
    "data" : {
      //Data in here is relevant if any of the above methods is used.
    }
  },
  {
    "methods" : ["bobspay.com"],
    "data" : {
      //Put some data in here that is relevant for bobspay.com payments only
    }
  },
  {
    "methods" : ["bitcoin"],
    "data" : {
      //Put some data in here that is relevant for bitcoin payments only (like the BTC price)
    }
  }
]

How do we ensure that the payment request from the merchant is not tampered with before it gets to the payment app?

If a merchant requests a payment, how can they be sure that their payment request is not tampered with when in transit to a 3rd party payment processor?

ACTION: Refactor flows to use common terminology and entry/exit points

The flows need to be refactored to:

• use a common set of actors/participants
• common terminology (preferably ISO20022)
• the same level of detail

Volunteers to assist are @adrianhopebailie, @vkuntz, @LaurentCastillo

What gets registered - apps, wallets, or payment instruments?

From Payment Method Registration Specifications:

One scenario is registering a new payment app. For example, this would allow bobspay.com to install an app into the user agent that would support transactions through the Payment Request API using the bobspay.com Payment Method Identifier.
Another scenario is that of registering specific Payment Method Data within a payment app. For example, this would allow a user logged in to the Alice Bank web site to register their Visa credit card with the Visa payment app.

I don't know if the text above is stating that you can register both 'payment apps' and 'payment instruments' within payment apps. I think it is. If so, it feels like too many levels of indirection because the user will end up having:

1. A payment app selection dialogue.
2. A payment instrument selection dialogue within each payment app.
3. A payment instrument verification dialogue within each payment instrument.

This means 3 clicks at a minimum to make a payment in the general, non-optimized case. It also means more cognitive load on the person (hmm, do I want to use my Google payment App with my Visa card, or my PayPal payment App with the same Visa card?). Can you share payment instruments between payment apps? That is, this has the downside of requiring the user to have a multiple wallets and multiple cards in each wallet metaphor.

The Web Payments CG specs attempts to reduce the cognitive load on the user. You register payment instruments, full stop. The payment app is defined in the payment instrument. This means the general, non-optimized flow is:

1. Select a payment instrument.
2. Confirm payment.

There is ONE discovery process to get a collection of all of your payment instruments into the browser. You select a payment instrument and you're directed to the site or app that handles the UI for that payment instrument/app. The benefit with this approach is that you can share payment instruments between payment apps w/o placing the cognitive burden on the person. They only care about their payment instruments (card metaphor).

Spec refs:
http://wicg.github.io/paymentrequest/specs/architecture.html#payment-method-registration-specifications
http://wicg.github.io/web-payments-browser-api/#payment-instrument-registration

[Architecture] Payment App is a term used in EMV to describe the applet stored in SC

Migrated from a thread on the Web Payments IG mailing list:
https://lists.w3.org/Archives/Public/public-webpayments-ig/2015Dec/0039.html

There is not a 1:1 relationship between a payment app and a payment instrument. I will update the documentation because this is misleading.

A payment app is more akin to a wallet but by using this terminology we do away with the fact that the wallet metaphor has not worked in our context.

For example, a user may register a payment app from their bank and this may support payments using all of the payment instruments they have from that bank.

While I recognise the closeness in terminology to EMV apps on a chip but I think the term app is most appropriate for what the component does and is sufficiently generic (and EMV sufficiently specialised a field) that this is not a problem.

Payment Request Architecture glossary should include IG glossary

The Payment Request Architecture glossary should import the Web Payments IG glossary. I have included all the terms in the PRA glossary in the Web Payments IG glossary and marked them as experimental.

An example of how to do this is in the Web Payments CG's Browser API spec:

https://github.com/WICG/web-payments-browser-api/blob/5034393370c54226eb13fbdacde2462ba5e11713/index.html#L170-L177

You will also need to include a script here:

https://github.com/WICG/web-payments-browser-api/blob/5034393370c54226eb13fbdacde2462ba5e11713/index.html#L13

which can be found here:

https://github.com/WICG/web-payments-browser-api/blob/5034393370c54226eb13fbdacde2462ba5e11713/utils.js

Spec refs:
http://wicg.github.io/paymentrequest/specs/architecture.html#glossary
http://wicg.github.io/web-payments-browser-api/#terminology

PROPOSAL: Adopt developer friendly-terminology for WG deliverables but root this in ISO20022 data dictionary through our published glossary.

Follows discussion of the question at #59.

PROPOSAL (from @mattsaxon )

In keeping with the WG resolution to try and root our terminology in the ISO20022 data dictionary the WG will adopt the following terms for use in its deliverables:

W3C Web Payments Term	Common Terms	ISO 20022 definition
Payee	Merchant	Creditor, Beneficiary
Payee PSP	Acquirer, Gateway	Acquirer, Intermediary
Payer	Shopper, Consumer, User	Debtor, Initiator
Payer PSP	Wallet	Intermediary

• We will use the W3C Payments Terms in the W3C specifications (to avoid writing out in detail).
• In the flows we would use the complete terms, however it should be realised that Common terms and ISO 20022 definitions may change between flows, for example for Direct Debit the ISO20022 term is Beneficiary, whilst for Credit Transfer it is Creditor.
• We will endeavour to have the W3C Terms added to the ISO repository as reserved words or ideally as specific mappings, e.g. a Payee is the superclass of both the subclasses of Creditors and Beneficiary.

How are payment apps shared between different browser brands?

In Phase I, when a user registers a new payment instrument, how is that payment instrument shared between different browser brands? For example, if I register a Visa debit card issued by my bank in Google Chrome on my laptop, when I go to purchase something using my mobile phone, is that same debit card available to me via my Firefox web browser (assuming I've authenticated in some way with both browsers)?

How would this change in Phase II or beyond?

How are third-party native wallets integrated?

Like a competitor to Apple Pay but running on multiple platforms including Windows, Android, and iOS.

PROPOSAL: Postpone release of an HTTP API FPWD until the messaging schemas have stabilized.

This proposal is related to the question at #17.

Some background:

• The WG decided that we should produce an HTTP API and we are chartered to so.
• There will be benefit to aligning the messaging used in both the HTTP API and JavaScript API.
• The group's efforts are currently focused on the JavaScript API and the design of this API is likely to impact the design of any messages that are exchanged via the API.

PROPOSAL
The WG should wait until the JavaScript API is sufficiently mature that the messaging schemas have stabilized and then design an HTTP API based on these schemas. This would mean not publishing an FPWD of an HTTP API in March.

How do organizations layer additional information in the core messages?

If we have a core set of payment messages, are they extensible?

If they are extensible, what is the extensibility mechanism?

Is the browser required to understand this extensibility mechanism?

How do we protect certain data in the messages from certain parties in the flow as the use case requires?

Split out from #19 which is focused on the need (or not) for digital signatures as a way of validating that the payment request is received as intended by the payment app.

In that thread @mattsaxon raised a requirement for payment apps to be able to return data that is hidden from the payee themselves (perhaps for PCI scope reasons) as they will pass it on to their PSP who can then decrypt it and use it:

Some elements in the payment response may need to be hidden from the merchant also (e.g. card number)

@CYV suggested SCAI as an option for standardisation of signing and encrypting data through a multi-party flow:
https://www.w3.org/Payments/IG/wiki/Main_Page/ProposalsQ42015/SCAI

So the question becomes; is field level encryption something that should be:

1. standardised and the Web Payments specs define this standard
2. defined as a best practice and the WG publishes this guidance
3. left entirely to the payment app publishers and payment methods to define as they see fit

PROPOSAL: Use strings to represent currency and amount per ISO20022

This proposal addresses the question in #40.

The ISO20022 dictionary defines a CurrencyAndAmount [1] data type for passing currencies and amounts in payment messages (as well as some updated version thereof with looser restrictions on the number of digits allowed).

In ISO20022 currencies are represented using the ISO 4217 [2] three-letter alpha code.

The decimal separator is a dot.

An example of an ISO 20022 currency and amount in XML:

<Amt>
<InstdAmt Ccy="EUR">1.00</InstdAmt>
</Amt>

PROPOSAL:

Use formatting rules for the Web Payments WG specifications as follows:

1. Amounts MUST be represented as an object.
2. The amount object MUST have at least two named properties: "currency" and "amount".
3. The value of the amount property MUST be a string consisting only of numeric digits.
4. The value of the amount property MAY contain a single dot to denote separation of the fractional suffix from the rest of the amount.
5. If present, the dot MUST NOT be the first character of the amount.
6. The value of the currency property MUST be expressed as a string of 3 characters.
7. If the currency is listed in the ISO 4217 Current Currency and Funds list the appropriate alpha currency code MUST be used.
8. If the currency is not listed in the ISO 4217 Current Currency and Funds list an appropriate and universally understood code SHOULD be used if available.

Example:

{
  "amount" : "0.12345678"
  "currency" : "XBT"
}

[1] http://www.iso20022.org/standardsrepository/public/wqt/Description/mx/dico/datatypes/_L8ZcEp0gEeOo48XfssNw8w
[2] https://en.wikipedia.org/wiki/ISO_4217

PROPOSAL: The Web Payments browser API should not support the collection of shipping information through API calls

Proposed by @msporny
Attempts to resolve #39

PROPOSAL: The Web Payments browser API should not support the collection of shipping information through API calls because there may be work starting shortly in the Verifiable Claims work and the Credential Management API that would almost immediately deprecate the mechanism. The Web Payments Browser API may support it via a key/value pair in the payment request data or options object passed to the API if the Verifiable Claims / Credential Management API fails.

Should a website be able to provide a label for the "Buy" or "Checkout" button displayed in the payment app?

Migrated from: https://github.com/WICG/paymentrequest/issues/46

@adrianba:

It may help users understand what they are accepting if the web site is able to label the "accept" button. For example, if a user is about to "Buy" something, "Reserve" something, "Subscribe" to something, etc.

@mattsaxon:

This is linked to the comment I just made on issue #65
+1 to distinctions as suggested by @adrianba

@ianbjacobs:

It seems there are several topics here:

1. The API may be used in a variety of user interactions, and the entity that displays the relevant payment apps may need a label to communicate the interaction to the user. Note that these labels may not be in English, and that the specification probably cannot prevent misuse of labels.
2. The API may be used in a variety of flows, such as "pay", "register", or "reserve". There may be hacky ways to implement the different scenarios, like using amount=0 to imply "register". However, we should consider whether we want to define a small number of verbs that become part of the data exchanged with the payment application. We will not be able to address every possible scenario, but I have now heard three that sound like it could be useful for the merchant to be able to pass on to the payment application.

Furthermore, it seems there is a relationship between this topic and a topic we discussed previously that translated in the following charter language: "The Working Group will consider support for deferred payment execution to enable use cases where the actual execution of a payment requires steps that are out-of-band with respect to the message flows and APIs defined by the Working Group." That was a use case where the user chose a push payment instrument, but the merchant did not want the payment to be completed before the merchant regained control of the flow.

Please let me know if this makes sense:

• The distinction between "what the user sees" (label) and "what the merchant wants to accomplish"
• We may wish to define a set of verbs so the merchant can communicate what they want to accomplish.

PROPOSAL: Hold WG meetings every week until further notice.

Per the discussion on the mailing list [1].

Our original intent was to meet weekly but alternating between “Americas” friendly times and “Asia Pacific” friendly times...
...despite having run the questionnaire twice, we only have responses from two people, only one of whom is in the AP region. [2]

PROPOSAL:

The group moves to a weekly conference call schedule in our current time slot (Thursdays at 17:00 UTC) with the chairs running a biweekly “catch up” session at an Asia-Pacific friendly time if requested by the group.

[1] https://lists.w3.org/Archives/Public/public-payments-wg/2016Jan/0058.html
[2] https://www.w3.org/2002/09/wbs/83744/WGconfschedule_eastern/results

Should we standardise a callback mechanism for payment apps to communicate to 3rd parties?

In #55 there is a discussion regarding the appropriate mechanism for a payment app to communicate with the website (other than receiving a request from the website and then returning a response).

An alternative mechanism for this (that does not require explicit support in the API) would be for the payment request to include a callback URL and for the payment app to send any notifications of important user interaction or requests for updated payment details to the payee system via that URL.

It's quite likely that payment apps will want the flexibility to communicate with the payee (or their PSP) after receiving the payment request but prior to responding back to the browser with a payment response.

On that basis it seems like a good idea to define a standard for providing this callback mechanism, either per payment method or universally.

Note: Such a mechanism is described in the Web Payments CG proposal (see step 6) but assumes this mechanism would only be used to contact a payer payment services provider. Such a callback doesn't need to be standardized as it will be defined per payment method.

Standardizing this could be as simple as defining an attribute(s) in the payment request where the URL for this callback should be provided (if supported) or as comprehensive as describing how this callback mechanism should be used (referencing the HTTP API possibly).

ACTION: Summarize arguments for/against shipping address capture

Create a wiki page to summarize the arguments for and against capturing the shipping address in the web payments API.
Consider making this one of a collection of pages which begin to summarize the discussion around big issues that will likely be tackled at the F2F.

Should the Web Payments API cater for the invoicing part of the full web purchase flow ?

Through web payments, the current usage does not provide a consistent approach for the provisioning of the invoice: together with the goods, by a confirmation email, embedded in order confirmation on the website. Should there be a consistent and harmonised approach, which would define specific requirements on the API.
Additional considerations: from a legal point of view, the provision of an invoice might have different implications. How can a standard API support this.

Confusion over payment flow

cc: @mattsaxon

I'm looking over the payment flows, in particular the 3Ds & Google Flow, and I'm not sure I understand the characters/roles that are laid out at the top of the diagram [1]. Namely:

• You seem to be conflating the user and the browser ("Payer (Shopper) Browser"), but these are distinct roles and I'm getting confused who is taking what action. Perhaps you really just mean "Browser" here? Since there's only one browser (or "User-Agent") in any given transaction, I don't think we need to be more specific here.
• I do not know what a "Browser Payment Agent/Wallet" and a "Payer (Shopper) PSP Wallet [aka Issuer Wallet]" are or how they differ.

Given the confusion above, I'm not 100% sure I follow the proposed flow. But it seems to suggest that the user selects a payment instrument from the browser window (I'm using our terminology here, where "payment instrument" is the thing the user selects inside of the browser UI), the user goes into the payment instrument, a blob of data is returned back, which then gets passed back to the merchant, and only then does the user get put through the 3DS verification flow.

While this is certainly one way to do it, I don't think it's preferred or ideal. The user should be put through and 3DS flow inside of the payment instrument before any data is returned to the merchant. The goal is to make things easier for merchants and put the complicated logic inside of the payment instrument and whomever is providing that instrument.

Sorry if I've misunderstood anything.

[1] I am using planttext.com to take plain text and convert it into actual diagram, so not 100% sure it's accurate

How are payment apps registered?

There are a variety of approaches that can be used to register payment instruments:

• Browser API call
• Installed by OS Platform (Android Pay, Apple Pay)
• Software installation (Chase Visa Card App)

Which one of these options are we going to support in Phase I?

Should we have separate specifications for payment and registration of payment apps?

The Payment Request Architecture diagram suggests that we split registration from payment. While I agree that the separation of concerns is good and helps both progress independently, I'm concerned that it also creates a very easy excuse for us to ignore the registration problem and may accidentally create an oligopoly in which the browsers and OS vendors control who can and can't register.

While I don't think any one of us wants to create an oligopoly, ignoring the registration problem is something that has a moderate chance of creating such an oligopoly. For example: "BigCorp requires all registering payment instruments to pass our payment instrument criteria (which, by the way, requires your payment instrument to have a total transaction volume of X, for you to pay us registration fees, and for your company to have existed for 10 years and have at least a millions of dollars in recurring revenue)".

So, if we split these specs, I'd only be okay if we commit to similar time frames.

To be clear, the registration process has several good technical approaches we could utilize:

1. Shared, centralized corporate community run registry.
2. Decentralized WebDHT-based mechanism.
3. Decentralized payment instruments as credentials.
4. Password-manager as registration vehicle (LastPass, etc.)

... and you can't do a payment until there is some registration process available (and polyfill-able).

Spec refs:
http://web-payments.github.io/web-payments-messaging/#payment-instrument-registration
http://wicg.github.io/web-payments-browser-api/#payment-instrument-registration
http://wicg.github.io/paymentrequest/specs/architecture.html#payment-method-registration-specifications
http://wicg.github.io/paymentrequest/specs/method-identifiers.html#issue-3

Security and Privacy Self-Review

The TAG has published a self-review questionnaire:
https://www.w3.org/TR/security-privacy-questionnaire/

This issue is to remind us to review it as part of our document review process.

Should a payment request be just data, or a programmable object?

The paymentRequest API asserts that a payment request is a programmable object:

http://wicg.github.io/paymentrequest/specs/paymentrequest.html#paymentrequest-interface

that is instantiated like so

var payment = new PaymentRequest(supportedInstruments, details, options, schemeData);

and can have methods called on it like so:

payment.addEventListener("shippingAddressChange", function (changeEvent) {
    // Process shipping address change
});

The Web Payments CG's Browser API asserts that a payment request is just data:

http://wicg.github.io/web-payments-browser-api/#processing-a-payment-request

and that data is processed by functions (see example in link above for a clear picture of what this looks like in practice).

These are two different general design approaches for the browser API:

1. There is data, and functions act on that data (Web Payments CG approach).
2. There are objects that consist of data, and verbs that hang off of those objects (paymentRequest approach).

So, what is our design approach for the browser API?