.pay() vs. .payment() vs. .initiatePayment()

[msporny]

This has more to do with naming the methods in the API. It may seem superficial at first, but the messaging to a developer is important. What exactly does the .pay() call do?

You can provide a JWT to do a payment, chargeback, or refund (eventually). So, pay() doesn't seem right. Maybe something like this would be better?

navigator.payment.pay()
navigator.payment.refund()
navigator.payment.chargeback()
navigator.payment.fund()

... but then the API might seem unwieldy for developers.

In addition, the PaySwarm specs allow you to do more than just payment. For example, the PaySwarm crowdfunding spec isn't necessarily a "payment", more like a "payment request" or a "payment intent". We discussed startPayment(), but that's a bit annoying to type and doesn't fully describe the action.

The API call is really an "initiation of value transfer". I think the current design, where you just pass a token of some kind that expresses the value transfer that you want to initiate, is good. That enables us to expand the types of value transfer that you can do in the future. We could do something like this:

navigator.payment.start()

... but again, .start() seems like a bad name. It's not as nice as the simplicity of navigator.pay(), but we may have to give up on that if this API is capable of supporting the range of stuff that's possible via PaySwarm.