[DOCS] Confirm incoming payment

[totten]

It's good idea having the "Guides" for the one-time payment and the recurring payment. This is just a little feedback about those guides (as a generalist reader/evaluator; not as someone using the system).

• If you're a merchant/recipient/payee, then you want a way to confirm whether payment has been received. (The confirmation should only be trusted if it comes from your own bank, right?) Near the last step, it would be great for the guide to point out how to do confirmation.

• I don't have the answer for your Guide, but let me free-associate to show the kinds of thoughts/questions that come up about confirmation.

  • For a one-time payment.. my guess is... at the end... we should poll the original incomingPayment for its receivedAmount and/or completed flag.

  • For a recurring-payment... it's not clear how the N-th outgoingPayment will correlate to confirmable data in the recipient's wallet:

    • Perhaps the N-th outgoingPayment is added to the receivedAmount of the original incomingPayment?
    • Perhaps the payer's N-th outgoingPayment causes the automatic creation of payee's N-th incomingPayment? (Recipients should scan their list of incomingPayments and find some metadata to match against?)
    • Perhaps the client is responsible for creating both the N-th incomingPayment and the N-th outgoingPayment?

  • In consumer payment systems in US/EU/etc, payments can be reversed. In the model, I don't see how you would identify a reversed payment.

• The examples sometimes show URLs. All the example URL's look like *.interledger-test.dev. I assume the actual URLs would tend to use different domains. (Some claims are asserted by payer ASE; others by the payee ASE.) The amount of trust that you put into the data varies by perspective. (The payee trusts data from one wallet; the payer trusts data from the other wallet.)

  It might be nice if example URL's hinted at which ASE was outputting the assertion.

• There are references to WALLET_ADDRESS and walletAddress. The use-cases actually involve two wallets (eg merchant/payee/recipient wallet and consumer/payer/sender wallet).

  In some steps, you can make an easy guess about which wallet to use. (Ex: For a Merchant-Consumer scenario, the step "Initialize Open Payments client" is probably the merchant's wallet. And for most of the other steps, it's probably the consumer's wallet.)

  But there are 10-13 steps in each guide. As you jump back/forth between steps, it might be easier to read with different symbols for the two wallets (e.g. MERCHANT_WALLET_ADDRESS vs CONSUMER_WALLET_ADDRESS; or PAYEE_WALLET_ADDRESS vs PAYER_WALLET_ADDRESS).

Anyway, that's a long list. I don't expect anyone to answer all my thoughts/questions in this discussion, and you don't have to take all these suggestions. But I wanted to register the feedback in case helps with the next iteration of the docs.