Re: Checkout API spec published

On 11 February 2016 at 13:19, Zach Koch <> wrote:

> 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.

In this case they'd likely use the checkout API for both but not request a
shipping address for the virtual good. Therefor we still have the low level
payment API for those that want it and the checkout API for those that want
to leverage the browser for more of the flow.

> * 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.

Which statement exactly?

> It could also be that I'm misunderstanding, but there are many UI patterns
> that could be taken advantage of to resolve any issues.

True, but there are design constraints we have to work within and I'm
trying to point one of these out.

> 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.

Agreed, implementors will do this how they want to but that doesn't change
what's technically possible. If you have a need to gather user input that
will affect the amount our current approach prevents you from getting a
choice of payment app before getting that user input.

That is not to say we can't revisit this architecture but we should
remember why we put it there in the first place. To protect user privacy.

We might consider a different architecture where a user is asked to pick a
payment app and the browser is returned some "proxy" to that app and it
submits the amount etc to that proxy but we need to consider how much info
that proxy gives away about the underlying payment app and what that
reveals about the user.

> Zach
> On Thu, Feb 11, 2016 at 8:30 AM, Adrian Hope-Bailie <
> > 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 <>
>> 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.

Received on Thursday, 11 February 2016 11:33:59 UTC