Add PaymentItem type to deal with transaction types

[adrianhopebailie]

The TransaactionType is a new property of the PaymentItem which helps
the user agent infer appropriate display logic for the payment such as
locale appropriate values display and button labels.

Addresses:
#56
#19

[zkoch]

I agree with the direction of this PR in general, but a few comments:

1.) We don't support refunds or credits, so I don't see the need to include those options. If this changes in the future, we can append those.
2.) I think it's unnecessary and too complicated to have the type specified per line item. It should be across the entire transaction.
3.) I don't full understand the difference between "capture" and "debit".
4.) There should be a default set across the entire transaction, which I would imagine is either "capture" or "debit".

[mattsaxon]

+1 for the journey applying to the paymentrequest, not the line items
+1 to removing unsupported transaction types for now

I think the enumeration should be (to start with); identify, authoriseDeposit, authoriseDebitOnShipment, ImmediateDebit. This enoumeration is a hint to the paymentapp.

The difference between Capture and Debit is the way settlement proceeds and I think not relevant to the journey (i.e. the hint), though the status returned back from the PaymentApp should enumerate what has occurred and could differentiate.

[zkoch]

I think the enumeration should be (to start with); identify, authoriseDeposit, authoriseDebitOnShipment, ImmediateDebit. This enoumeration is a hint to the paymentapp.

@mattsaxon Can you explain each of these?

[mattsaxon]

Sure, from issue #19, here are the uses cases I identified;

1. Immediate Payment (my view is that this is the implied use cases for the API as it currently stands)
2. Payment on shipping of goods/provision of services (i.e. authorise now, but request funds when the goods are shipped - note many credit card Ts&Cs require this approach): [Ref: IG use-case 6.3.3]
3. Funds Hold (e.g. for a hotel room deposit, where you may pay by an alternative means later) [Ref: IG use-case 6.1.1: Hold Funds (currently this is not categorised into Phase 1, but I believe it should be - I think it is a more common use case than Refund, see number 7 below)]
4. Recurring Payment (subscription) with a specific schedule. [Ref: IG use-case 6.1.2: Subscription]
5. Registration (as above, but when the payment instrument is kept on file for later use) [no specific use case identified, but implied by IG use case 6.1.2 Registration-less]
6. Identification of a individual (i.e. not a payment) [Ref: IG use-cases in 6.2.3]
7. Refund (whilst we haven't discussed this in the WG to date, and I think we've implicitly assumed it to be out of scope) [Ref: IG use-case 6.4.3]

'identity' maps to item 6
'authoriseDeposit' maps to item 3
'authoriseDebitOnShipment' maps to item 2
'immediateDebit' maps to item 1
items 4 & 7 are not yet supported by the API
item 5, I see, needs another enumeration added, I suggest 'registerPaymentCredential' or similar.

I'm sure we can find better, more consistent descriptions, but hopefully this conveys the gist.

[halindrome]

Those are good descriptions actually. A nit though - we tend to use American English spellings... so authorizeDebit

[zkoch]

Thanks, very helpful. Few thoughts:

1.) I can see the need for immediateDebit and I would support that being the default type for a PaymentRequest if none is specified.
2.) Do we need to separate out the authorization types? It seems just having a single authorization might be enough for our purposes.
3.) I don't understand identity. Based on your definition, it doesn't seem like we're trying to support this use case.

[adrianhopebailie]

The list of transaction types comes from an analysis of the existing types offered on a variety of existing payment gateway APIs. (Search for "Transaction Types" and see what you find. I took those that seemed appropriate and found simple terms that were a good aggregation and seemed easy to understand for a lay developer).

These types serve two purposes:

1. To assist the user agent to display the line item amounts correctly considering internationalization and possibly hints (like an icon) that reflects the transaction type.
2. To assist the payment app in understanding how to process the payment.

NOTE: The terminology "debit" and "credit" are appropriate payment terms and their use aligns with our resolution to follow ISO20022 terminology where appropriate

@zkoch said:

We don't support refunds or credits, so I don't see the need to include those options. If this changes in the future, we can append those

Who is we in this context? Google or the WG? Surely the supported transaction types is determined by the payment service providers involved (all of whom appear to support credits/refunds based on my research). i.e. If the merchant supports credits/refunds and the payment app does to why prevent these transactions by restricting the API?

Obviously there is an implicit requirment that a merchant allowing an online refund will ensure that the payment methods they list in the request all support credits (the same applies for all of the other transaction types)

I think it's unnecessary and too complicated to have the type specified per line item. It should be across the entire transaction.

The per line item type allows you to include credit line items like discounts which should be displayed differently to, for example, a sub-total which is a debit. Remember that CurrencyAmount is supposed to be an unsigned number (per our resolution w3c/webpayments#57) - see PR to correct it: #101

I don't full understand the difference between "capture" and "debit"

Based on what I read on other APIs "capture" is the process of capturing the payment details for future use whereas debit is an immediate payment. I'm not married to "capture" as a type but I think we should have "debit" and "credit".

There should be a default set across the entire transaction, which I would imagine is either "capture" or "debit"

The default is "debit" but for some reason when I put that in the WebIDL it wouldn't compile properly so it's mentioned in the spec text.

@mattsaxon, I think we should support all those use cases (including recurring payment and refunds) although I'm unclear on "identify" and why this is in scope?

All that is required for the API to support these use cases is to list the transaction type in this enumeration. Whether the transaction is supported by the payee or the payer payment app is dependent on the payment method that is used. I see no reason for us to restrict this intentionally.

In terms of the actual terms I am wary of us being too card-centric here which is why I have used more generic terms like "debit", "credit", and "authorization". I think ISO20022 verbs are the right things to use because these encompass a more full breadth of payment flows.

That said, I'd invite some input from @mountielee on whether we need explicit terms for escrow or any other payment types we have missed here.

Really, this list should be an aggregate, simplified, list of the transaction types supported by the various payment service providers that will publish payment apps and process payments for payees. As mentioned in the included issue marker we might want to make this list extensible.

[davidillsley]

Matt's suggestions make more sense to me if the intention is to allow the payment app to give a better user experience. That multiple user experiences map onto a single underlying transaction implementation type doesn't mean that those terms are the most useful ones in this case.

[mattsaxon]

@zkoch

re: 1, I'd prefer the requirement to actually think about what the transaction type is. As it happens, with cards today, scheme rules dictate that the default (when there are good involved) is authoriseDebitOnShipment.

re: 2, the difference in authorize are to do with the 'contract' with the payee that is being accepted when they hit the 'Buy/Checkout/whatever' button. authorizeDeposit (not Debit) is an implication that funds are being put on hold, but will not be charged unless something untowards happens (trash your hotel room, crash the hire car).

re 3: this pertain to various use cases; today card authorisations are used to prve who you are, . often this is related to an initial purchase, e.g. pick up prepaid tickets. This is today often done with a "0$ auth"

[adrianhopebailie]

Matt's suggestions make more sense to me if the intention is to allow the payment app to give a better user experience. That multiple user experiences map onto a single underlying transaction implementation type doesn't mean that those terms are the most useful ones in this case.

This sounds too much like we are dictating to the payment app what the user experience should be.

The intent here is for the payment app to correctly reflect to the user what is being requested. i.e. Is this just an authorization or will you be charged when you authorize this transaction? Am I signing up for a subscription service or a one-off payment? Is this payment in some way tied to the delivery of goods so I know the payee won't be settled until after the goods have been shipped?

Perhaps this can all be conveyed in the payment method data in the request but it seems sensible to have a standardized list that is agnostic to avoid this becoming very fragmented.

I want to emphasize again that we shouldn't make this list too card-centric. If our transaction types are not generic then the choice of transaction type by the merchant immediately imposes a restriction on the payment methods they'll offer which is counter to our goal of making it easy to introduce new payment methods on the Web.

My suggestion is that we merge this with the addition of an issue marker pointing to a new thread discussing the appropriate set of transaction types.

[mattsaxon]

I want to emphasize again that we shouldn't make this list too card-centric. If our transaction types are not generic then the choice of transaction type by the merchant immediately imposes a restriction on the payment methods they'll offer which is counter to our goal of making it easy to introduce new payment methods on the Web.

I don't believe the suggestion is too card centric, I simply offer that up as examples both as people are familiar with these and we have a BasicCard specification in draft.

[adrianhopebailie]

I simply offer that up as examples both as people are familiar with these and we have a BasicCard specification in draft.

Good point! Would it be sensible to assume that as we produce payment methods specs to reflect all of the flows we consider in scope that we will be able to adjust this list to reflect a good aggregate set that covers all of these?

Rather than discuss this directly on this PR, let's use the orginal issue at #19 and I'll add an issue marker to this PR pointing to it.

[mattsaxon]

Agreed. We can move to issue #19, however I think we need the parameter in the right place and I think the consensus above say it should be paymentrequest wide

[adrianhopebailie]

I think we need the parameter in the right place and I think the consensus above say it should be paymentrequest wide

The way it is currently implemented the type of the last payment item in the sequence is the type for the whole payment request. The types on other preceding items simply provide UI hints for the user agent.

If we don't like giving the "last item in the sequence" special treatment then we should consider moving the total amount out of this list too and putting it somewhere that is "paymentrequest wide".

[mattsaxon]

I agree the specific treatment feels wrong and believe there is another issue out there where the same is being said for 'total', I would support splitting out both.

[adrianhopebailie]

I would support splitting out both.

That is a bigger edit but will try to throw something together today.

[adrianhopebailie]

Have made a quick change to the PR to pull total out of the items list.

I wonder if re-using PaymentItem is a good idea or if total should be a stand-alone CurrencyAmount and transactionType a separate attribute of PaymentDetails?

[halindrome]

See #18 - I think it should be a separate attribute...

[triblondon]

Regarding use cases for recurring payments, it may be worth separating different aspects of persistent payment authority:

• Variability of the value: Some authorities will allow the merchant to change the transaction value on each charge, which is useful for metered services like AWS or your mobile phone bill. Others theoretically don't need that ability, say a digital subscription (though prices do rise with inflation so in practice merchants often build the ability to do that into their initial agreement with the subscriber)
• Variability of the schedule: Some methods allow merchants to charge whenever they like, others might require the merchant to submit no more than one charge per month, for example.
• Strength of the authority: In the UK the most common recurring payment mechanism is direct debit, which offers merchants variable value, variable schedule authority, but offers payers a guarantee of any dispute being instantly resolved in the payer's favour. Conversely continuous payment authorities are much harder to revoke and are often used for loan repayments. Of course whether the payer has a contractual obligation to pay the merchant is out of scope here but the level of invasiveness of the payment method is probably of interest.

I don't think the subtleties above are adequately captured by the proposed transaction types, and wonder if that is a problem.

[adrianhopebailie]

I have done an about turn on this after preparing PR #133.

I think we should leave this entirely up to the payment method to define because, as we are discovering, the specifics are important AND should be the domain of the payment app to worry about.

Consider the complex set of recurring payment scenarios that @triblondon has described above. I would imagine that the rules for these are codified by payment schemes that support them. This suggests that there will need to be payment methods that indicate how the data is exchanged to initiate and process these different authorizations. Further, the payment apps that claim support for these payment methods should then be able to interpret the different transaction types for a specific payment method.

The only thing I think we can still standardize at the PaymentRequest level (as opposed to payment method data level) is a mechanism for the merchant to define an obligation (per #113).

I am going to close this in favor of #133 and suggest that the card specific transaction types could be added to the basic card spec.