[Draft] Deep Link Payment Protocol

BIP: ?
Layer: Applications
Title: Deeplink Payment Protocol
Author: Shun Usami<[e-mail]>, 
        Taiki Uchida<[e-mail]>,
        Aoi Serikawa<[e-mail]>
Comments-URI: https://github.com/bitcoincashorg/bitcoincash.org/pull/145
Status: Draft
Type: Standards Track
Created: 2018-10-21

Abstract

Basically this is just a BIP21(URI scheme) like deeplink scheme to wallet applications with a callback url.
When the wallet app completed the requested behaviour, the wallet app ping the callback URL.

Motivation

Currently, the payment experience on mobile devices are very bad, because users have to take many steps like this.

• 1. Copy the address.
• 2. Open a wallet app.
• 3. Paste the address.
• 4. Type the amount to send.
• 5. Send to the address.
• 6. Re-open the source application.

This protocol dramatically reduces the user's required steps.

• 1. Opens the deep link to a wallet app.
• 2. Confirm payment and automatically returns to the source app.

Specification

Deep link Scheme

This deep link scheme is protocol for communication between wallet application and another application.

i.e.
bch-payment:{parameters}
bch-sign:{parameters}

title	value
Custom URL scheme	bch-{type}

type	explanation
payment	request a payment to wallet application
sign	request signing of message to wallet application
coming soon	coming soon …

Mobile App to Wallet App Communication

1. Source app generates deep link to wallet app

The source app generates a deep link to wallet apps.
i.e.
bch-payment:{addr}?amount={amount}&callback={callback_url}

addr is a cashaddr without scheme.
i.e.
qznj9wsazh379qa3dkph7qvtxdx5emkrxvsxhnyall

Query key	type	memo	example value
amount	Decimal	Coin value to send	0.0001
callback	String	deep link	yenom://payment-result

2. Wallet app make the payment

The wallet app build the payment transaction and broadcast it.

3. Wallet app opens the deep link to the source app

The wallet app opens the deep link to the source app after broadcasting the payment transaction or cancelling the payment.
callback_url?txid={txid}&status={status}

Query key	type	memo	example value
status	String	Status of the payment result. [success/error/cancel]	success
txid	String(optional)	Transaction id of the payment. Required if the status is success.	0eac357541b0ba572849113c5faa1d1990f6382741dc3e2f5507e3ca8346dc0e

4. Source app verify the tx with txid

Source app should verify the payment is done.

Web App to Wallet App Communication

1. Source web site generates deep link to wallet app

bch-payment:{addr}?amount={amount}&webhook={webhook_url}&callback={callback_url}

addr is a cashaddr without scheme.
i.e.
qznj9wsazh379qa3dkph7qvtxdx5emkrxvsxhnyall

Query key	type	memo	example value
amount	Decimal	Coin value to send	0.0001
callback	String	web link	http://yenom.tech/payment-result
sessionid	String	website session id	eyJ…3mh8

2. Wallet app build transaction with OP_RETURN output

The wallet app build and broadcast tx.
This tx should contain OP_RETURN output. This OP_RETURN output should store the SHA256 hash of session id.

Transaction 0eac357541b0ba572849113c5faa1d1990f6382741dc3e2f5507e3ca8346dc0e - Bitcoin Cash (BCH) Block Explorer

3. Wallet app pings the webhook URL

The wallet app send http POST request to webhook_url after broadcasting the payment transaction or cancelling the payment.

The webhook URL must accept a POST request with JSON. The object sent from the wallet app looks like this:

{ 
    "status" : "success",
    "txid" : "0eac357541b0ba572849113c5faa1d1990f6382741dc3e2f5507e3ca8346dc0e"
}

4. Wallet app opens the callback URL

And then it opens the callback_url as well.

callback_url?txid={txid}&status={status}

Query key	type	memo	example value
status	String	status of payment result. [success/error/cancel]	success
txid	String	Transaction id of the payment. Required if the status is success.	0eac357541b0ba572849113c5faa1d1990f6382741dc3e2f5507e3ca8346dc0e

5. Source website verify the tx with txid

Source app should verify the payment is done. And also check the hash of the user's session id corresponds with the OP_RETURN output of tx.

Rationale

This protocol is quite simple.
Alternative BIP70 like design can be considered.

Forward compatibility

Adding optional parameters can be done by simply adding them.
Adding required parameters or destructive change can be done by simply changing the type name to new one.
i.e.
bch-payment -> bch-payment-v2

Reference implementation

Coming soon.