Re: Checkout API spec published

I wonder if we are yet in a position to suggest that there are well defined
schema.org terms that map to various items?  To the extent possible, I
think it would be great if we could rely upon well-defined semantics and
then allow for local translation or whatever.  For example, the
UnitPriceSpecification [1] feels like a decent way to capture pricing on
individual items.  I would be happy to pull in someone from that community
to advise us if there is interest.

[1] https://schema.org/UnitPriceSpecification

On Thu, Feb 11, 2016 at 2:47 PM, Manu Sporny <msporny@digitalbazaar.com>
wrote:

> On 02/11/2016 02:34 PM, Doug Schepers wrote:
> > It wasn't clear to me how the the relationship between product
> > price, tax amount, and shipping amount are delineated or described.
>
> I can only answer for the Checkout API spec (which is largely modeled
> after the Microsoft/Google PaymentRequest API):
>
> https://wicg.github.io/web-payments-browser-api/checkout-api.html
>
> So, some of these answers also apply to the Microsoft/Google
> PaymentRequest API, but I expect that Zach and AdrianB will answer for
> that spec.
>
> > * Is it expected that the English string-literals "tax" and
> > "shipping" will be used? (I'm assuming not, since that's in the
> > client-side code.)
>
> If you are referring to this code:
>
> if(item.id === 'tax') {
>   item.amount = calcTaxAmount(checkoutDetails);
> }
>
> ... the client-side code (developer) set item.id to 'tax'. They could
> just as easily have set it to "myMerchantTaxCalculationLine" or "税金".
>
> > * Is the FinancialAmount amount the total amount, including tax and
> > shipping?
>
> Nope, a FinancialAmount is associated with every single PaymentItem in
> the "shopping cart". FinancialAmount is used with each PaymentItem,
> which pulls in CheckoutItem's properties via prototypical inheritance:
>
>
> https://wicg.github.io/web-payments-browser-api/checkout-api.html#paymentitem-dictionary
>
> Note that "State Tax" would be it's own PaymentItem, as would
> "Shipping", as would "Food Tax". Each one is a line item that's shown
> to the payer before they buy something.
>
> Note that this mirrors the design in the Microsoft/Google PaymentRequest
> API. I have concerns about it.
>
> For example, there is no clear internationalization story here for
> multi-lingual payment requests and line items, so that's still floating
> out there. How do you display a payment request in Hong Kong for payers
> that may recognize either English or Kanji (there are payment terminals
> that do this today)?
>
> > Does that meet every payment flow and international legal constraint,
> > or is there some reason to separate them (maybe for reporting
> > reasons?
>
> No idea, but I wouldn't expect it could. We haven't been able to do that
> work yet. To put it another way, I think the line-item thing is purely
> informational (browser display purposes) and naive and couldn't be used
> to generate a legally binding bill of sale in all jurisdictions in its
> current form. GS1 and NACS (and their European counterpart) probably
> have a ton of thoughts on this and we should check with them.
>
> > * In the PaymentItem dictionary, there's a boolean for shipping…
> > should there also be one for tax? (Some items in the same order may
> > be taxed differently, for various reasons.)
>
> This is a hold-over from the Microsoft/Google PaymentRequest API. That
> spec treats shipping information in a very special way and treats taxes
> as just another line item. This is one of the objections we had on the
> design as it special-cases shipping in ways that bleed into the API
> design. For example, something better might be that line items could
> have a "purpose" property with certain well-understood purposes that a
> user agent would use to specially format the display for the line item.
> Or we could have a "highlight" property.
>
> We should avoid special-casing things like this as much as possible, but
> I didn't remove it from the spec yet to keep the number of changes to a
> minimum.
>
> > * Are tax and shipping the only items? Will there be multiple types
> > of taxes, like sales or VAT tax, or is that all calculated by the
> > merchant at the time, and thus irrelevant to the API.
>
> Yes, there are multiple types of taxes and some merchants choose to
> display these tax lines separately. For example, there may be taxes that
> merchants want to break out from their service/product fees (e.g.
> breaking out a rental tax (renting out part of a restaurant) from a food
> sales tax (buying food). David Ezell would be able to regale you with
> stories on all the ways taxes are calculated and displayed during the
> checkout process.
>
> -- manu
>
> --
> Manu Sporny (skype: msporny, twitter: manusporny, G+: +Manu Sporny)
> Founder/CEO - Digital Bazaar, Inc.
> blog: Web Payments: The Architect, the Sage, and the Moral Voice
> https://manu.sporny.org/2015/payments-collaboration/
>
>


-- 
-Shane