Simple Website Payment

This DRAFT is similar to PayPal, E-Gold SCI and should be simple to implement for merchants.

The use case is basically:

User makes a one off purchase on a website.

1. hits checkout button on website
2. is presented with checkout screen
3. selects an asset provider from one of websites supported providers
4. is redirected to asset providers payment page
5. is displayed a payment confirmation page with amount, description and recipient from checkout screen
6. presses confirm payment button
7. funds are transfered to websites account
8. asset provider makes callback to website to verify that payment has been made
9. user is redirected to website

So the basic idea is that we need a GET URL that a user can be redirected to that populates a payment screen.

If we use the nubux example:

http://nubux.heroku.com/

Basic payment details

There is already a Pay view:

http://nubux.heroku.com/transacts/new

How about if we use the exact same parameters as in a REST payment: to, amount and memo just as query variables.

http://nubux.heroku.com/transacts/new?to=sales@beerpals.com&amount=10.00&memo=1+sixpack+of+Pilsner+Urquell

This would present a non editable version of the payment form, where the fields instead are hidden fields and text labels. The user then has to confirm this.

Callbacks

We need some way of letting the merchant know that the payment went through. We also need to redirect the user somewhere after a payment has been made.

Most payment systems allow merchants to specify 2 different callbacks:

• payment callback – Similar to PayPal’s IPN. The Asset provider makes an http POST to a provided url
• redirect url where the user is redirected to after payment

I propose that we keep the simple parameter approach and use the following parameter names to specify these:

• callback_url
• redirect_url

The callback_url should accept a POST and redirect_url should accept a GET.

Callback Data

The data sent to both urls should be pretty much the same. I can’t see a good reason why not anyway.

Data should be url form encoded. Every single platform supports this and it works well with OAuth.

All transactions should have a status field:

status=[ok|decline]

Most current payment systems have all sorts of complicated states as they have to integrate with bank systems, credit card systems etc. I think but I may be wrong that these 2 are all we need. I was even playing with the idea of using http status codes [200|403] but we should probably err on the side of readability.

‘ok’ should be used when the payment was successful. ‘decline’ should be used whether the user declined the payment or funds are not available.

Successful transaction:

• status: ‘ok’
• txn_id: url of transaction eg. http://nubux.heroku.com/transacts/1234
• from: payer account
• to: payee account
• amount: payment amount
• txn_date: transaction time (ISO 8601)

Declined transaction:

• status: ‘decline’
• description: optional textual description of failure

Signing of Callback

While it is impractical (I think) to prevent forgery of the redirect_url. It is important that the callback itself can’t be forged.

The callback should be OAuth signed. TBD

Extra Merchant Data

Merchants might want to send extra data along. My instinct is that they should encode that in the callback or redirect url’s however maybe we should allow extra fields to be sent along. Ideas?