Re: Checkout API spec published

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/

Received on Thursday, 11 February 2016 20:48:03 UTC