Checkout API spec published

Hi all -

I've been mulling this over the last week, and I've posted some thoughts
below. Hopefully we can talk more about this on today's call:

* I don't think we should break this out into two separate APIs. I would
still prefer a single API that developers can use in a consistent way to
get the information necessary to finalize a transaction (i.e. payment
credential, potentially a shipping address). For example, if I'm a game
developer and I run an online store that sells both virtual goods and
physical goods (apparel, card decks, etc), it's strange to me that in a
pure virtual good flow I wouldn't use checkout() but in a physical good I
would use checkout. There should just be a single paymentRequest (or
checkout if we prefer that naming) API.

* From an API perspective, I do think there is a nice level of cleanliness
(not sure of the right word) to Dave's proposal and the way information is
requested. I think we could potentially use this and it provides room for
expansion later (e.g. request invoice, request favoriteColor). I've been
traveling this week in Europe so I haven't had a lot of time to play around
with the API, but perhaps we could do something like:

paymentRequest = new PaymentRequest(...initialParams);
paymentRequest
  .request('shippingAddress')
  .show()
  .then(function(paymentResponse) {

  });

I also would prefer an event-based mechanism for thinks like
shippingOptionChange and addressChange. It just feels cleaner.

* To Adrian's point about UI, I'm not sure I agree with that statement. It
could also be that I'm misunderstanding, but there are many UI patterns
that could be taken advantage of to resolve any issues. But more
importantly, I want to make clear that we aren't necessarily advocating for
"a single UI screen" but instead a consistent user experience. These aren't
necessarily the same thing.

Zach


On Thu, Feb 11, 2016 at 8:30 AM, Adrian Hope-Bailie <adrian@hopebailie.com
<javascript:_e(%7B%7D,'cvml','adrian@hopebailie.com');>> wrote:

> Dave has some time on today's call to discuss his proposal which will give
> him an opportunity to expand on some of the motivations and design
> decisions.
>
> One thing that I think we need to consider is that, whether we use this
> API or not, it is almost impossible to present a single UI to the user for
> selecting shipping details and also payment app.
>
> The demo UI from AdrianB shows all of these in a single UI but that won't
> work with the architecture we have today. Today we combine the set of
> supported payment methods and the amount in the payment request so it
> follows that the user can only be prompted to select a payment app (based
> on payment method) after the amount has been finalized.
>
> If we feel like the website needs more control over this flow (select
> payment app and then provide amount separately) we need to consider how we
> can acheive that without compromising user privacy (i.e. we don't allow
> websites to take the user through the app selection process without
> actually requesting a payment)
>
> On 11 February 2016 at 03:16, Dave Longley <dlongley@digitalbazaar.com
> <javascript:_e(%7B%7D,'cvml','dlongley@digitalbazaar.com');>> wrote:
>
>> On 02/10/2016 02:39 PM, Rouslan Solomakhin wrote:
>> > Hi Manu,
>> >
>> > I've looked over the Checkout spec. It's a great start. There's one
>> > issue to resolve.
>> >
>> > The browser can signal the merchant only by resolving the promise that
>> > calls finishCheckout() in your examples. In the course of a checkout,
>> > it's conceivable that the user selects shipping option 1, then shipping
>> > option 2, then shipping option 1 again. Your examples show
>> > recalculations of the line items with a call to
>> > checkout.send('paymentItem', checkoutDetails.items) when this happens.
>> > The checkout.send() function is synchronous. After calling it, the code
>> > steps down to the line that requests the payment. However, the user has
>> > not finished selection their payment options yet.
>> >
>> > I can see 2 ways to resolve this issue from the top of my head:
>> >
>> >  1. checkoutDetails should have a "finished" boolean field. This is set
>> >     to false when user changes shipping options. It is set to true when
>> >     the user clicks "Buy". The merchant has to check this field.
>> >
>> >     if (!checkoutDetails.finished)
>> >       checkout.continue().then(finishCheckout);
>> >     else
>> >       checkout.finish(...);
>> >
>> >  2. Fire events instead of resolving a promise when the user selects a
>> >     shipping option. Usage of your API would change slightly.
>> >
>> >     var checkout = new Checkout();
>> >     checkout
>> >         .onEvent('shippingOptionChange', recalculateLineItems)
>> >         .show()
>> >         .then(finishCheckout);
>> >
>> >     // Returns line items with updated price/tax/etc based on the
>> >     options that the user has selected in checkoutDetails.
>> >     function recalculateLineItems(checkoutDetails) {
>> >         ...
>> >     }
>> >
>> >     // Requests the payment from the browser.
>> >     function finishCheckout(checkoutDetails) {
>> >       checkout.finish(...);
>> >     }
>> >
>> >
>> > I prefer option 2, because it's harder for the merchant to accidently
>> > charge you before you've finished selecting your payment and shipping
>> > options. What do you think?
>>
>> The merchant can't accidentally charge you -- they need to receive a
>> payment acknowledgement first. The payment acknowledgement won't arrive
>> until the user is taken to the appropriate payment app, which should
>> only happen after they've clicked "Buy". So I like option 1 better,
>> which keeps the flow control more obvious.
>>
>>
>> --
>> Dave Longley
>> CTO
>> Digital Bazaar, Inc.
>>
>>
>