API flow

[mattsaxon]

Added Basic API flow diagram to specification to show standard use of the API.

[adrianhopebailie]

@mattsaxon can you include submission of the original .PUML file into the repo as part of this PR? We can update the image src when it is merged.

[adrianba]

I have a few comments on this PR:

• This is quite a complex UML diagram and I don't know if adding this makes the specification easier to understand.
• There are parts of the UML diagram that are implementation dependent and not necessarily required by the API.
• The formatting of the (large) diagram makes it hard to fit into the document.
• This feels like a good thing to include in a primer document but I don't think it is necessary for the spec.

[mattsaxon]

you make a good point on the complexity. I'd like to seek others opinions on if the diagram should be external to the spec or if I should work on a more simplified diagram to include in the spec. Or indeed both?

In terms of implementation dependence, this could either be provided as an example externally or I could remove the implementation dependence and keep it strict and in the spec.

The purpose of this PR is to see if any type of flow would be useful and if it is then we should accept this PR and then revise the flow in future PRs IMO.

[ianbjacobs]

I have been thinking that the spec would benefit from a diagram, but I have been thinking the diagram should be in an appendix. I can also see the benefit of a simplified diagram with links to the more complete diagrams in the flows repository.

Ultimately I think we should decide based on the content of the diagram and the value it adds to the spec (and we can figure out formatting separately, use of SVG, etc.).

Matt if you are game to try a simplification, that would be interesting to me.

Ian

[mattsaxon]

Sure, I'll try a simplification, does that mean we merge this PR or close it? My understanding was that the consensus view was to iterate quickly and hence favour acceptance over rejection, then others can contribute too and see the progress.

[adrianhopebailie]

@mattsaxon we don't need to merge it or close it unless you'd like to close it.

I'd suggest simply pushing some changes to satisfy the comments made by @ianbjacobs and @adrianba and letting the conversation continue in this thread until there is consensus to either merge or close.

[mattsaxon]

I've worked on a simplified diagram, taken it from 28 interactions down to 20 and from 6 actors down to 5. Hopefully this makes it more useful and relevant.

[ianbjacobs]

@mattsaxon,

Thanks for working on the diagram. Here are my thoughts:

• +1 to a diagram (such as this simplified one) that shows how the different elements of paymentRequest fit into a typically payment flows. I think it helps give a picture of the API.
• Because it is specific to "how this API works," I think it's fine to have it in the paymentRequest API spec as an appendix.

Ian

[adrianhopebailie]

Here is the image for those wishing to review and comment:

I like the idea but I don't think we should separate the mediator and browser in this spec (because this is a spec describing how the browser assumes the role of mediator so in this context they are the same thing).

I'd also like it if the PUML file was being submitted as part of the PR so that we can make edits directly to the diagram from this repo.

[adrianhopebailie]

@mattsaxon - a few more comments on the diagram

1. As I mentioned above, this diarm is specific to the browser context where the browser and mediator are the same component so these could be merged.
2. To keep it limited to the scope of the spec I'd start from step 3 and end after 18
3. The diagram presumes that there is only 1 payment provider involved whereas the provider that the website communicates with may be different to the one the app communicates with.

[adrianhopebailie]

@mattsaxon - I have made the changes I suggest on my own fork:

[adrianhopebailie]

Not discussed on 12 May, postponed to 19 May

[fredMeignien]

I think it would helpful to describe the functions of each actor/component underlying the flows, and highlight where changes are in comparison with legacy.
For instance

• store customer data
  today, it can be the Merchant and/or the Merchant PSP (shipping address, card data) allowing such thing as the "one-click payment" of Amazon)
  with the API, storage is done on the device where the payment app is managed (mobile phone wallet, browser wallet...)
• create the payment form and send it to the browser
  today, Merchant and/or his PSP
  with the API, the API does it via the browser
• fill the form
  today, pre-filled with stored data, or filled by the payer
  with the API, the API does it via the mediator, so there is no manual data entry
• send the payment data to the Merchant PSP
  today, as the payment page is provided by the Merchant or his PSP, it is their responsibility
  with the API, the API interacts with the PSP
• send the payment data to the issuer (payer PSP or Scheme or Scheme+payer PSP)
  today, done by the Merchant's PSP
  with the API : hum, could be the same, but maybe the Merchant could do it himself,
• get in return the approval from the Issuer or Scheme+Issuer
  done by the Merchant'PSP in both cases
  ...
  I am not sure to have the good answers !!

By the way (this is not a flow problem, but an important ulterior thought) this would help providing responses to merchants and acquiring PSP who have important strategic questions as: I want to know what I need to change on my site, which interface I should use, can I find here a strategic advantage and so on.
If things get easier, a direct consequence is that all this will accelerate the dis-involvement of banks from the payment processing market, and give room to many kinds of new actors.

[fredMeignien]

To finalize the transaction, the Payee PSP generally exchanges a request/response with the Payer PSP, who authenticates the payer and approves the amount ; this is typical in card flows.
I guess this exchange takes place between flows 12 and 13. Is it right ?

[adrianba]

There's a lot of discussion here about informative content describing how to utilise the API. We have also received other questions and feedback to the working group indicating the need for a primer document explaining how to best take advantage of the API and how flows might work.

I can live with adding this diagram if that is the consensus of the group but I strongly recommend that the group consider picking up work on such a primer document rather than adding this to the normative implementation specification. There appears to be sufficient discussion and interest in the topic that such a work stream would be successful.

[adrianba]

Closed per F2F discussion.