Exchange notifies processor of payments

bip-xxx.mediawiki

@@ -0,0 +1,158 @@
+<pre>
+  BIP: XXX
+  Layer: Applications
+  Title: Crypto Open Exchange Protocol (COX)
+  Author: Nicolas Dorier <nicolas.dorier@gmail.com>
+  Comments-Summary: No comments yet.
+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-XXX
+  Status: Draft
+  Type: Standards Track
+  Created: 2017-12-20
+  License: BSD-3-Clause
+           CC0-1.0
+</pre>
+
+==Abstract==
+
+A simple protocol for decoupling payment processor solutions from exchanges.
+
+==Motivation==
+
+Cryptocurrency merchant adoption is mainly driven by availability, ease of use and means of acceptance.
+We call such solutions `Payment Processors`.
+
+Until now, payment processing solutions fall into one of the two following categories:
+
+# Self-hosted with the customer paying in cryptocurrency and the merchant receiving it directly.
+# Centralized, coupled with an exchange feature, with the customer paying in cryptocurrency to the merchant, and receiving fiat or cryptocurrency on his exchange account.
+
+The self-hosted solution has two issues:
+
+# The merchant becomes vulnerable to the wild volatility of cryptocurrencies.
+# If the merchant does not pay suppliers in crypto, it is wasteful of blockchain space as a second transaction is needed to send to the exchange,
+
+The centralized solution has two issues:
+
+# It locks-in the merchant to a particular payment processor whose intentions might not be aligned (e.g. Bitpay who tried to redefine Bitcoin as being a different chain, without merchant approval)
+# It has to deal with local regulations (e.g. Bitpay does not provide fiat CAD to canadian merchants)
+
+The goal of this BIP is to specify a simple protocol which makes possible decoupling of payment processors from exchanges.
+
+We believe this BIP will gather a lot of interest among local exchanges which do not have the resources to develop their own payment solutions.
+
+Their customers can decide which payment processor solution they prefer, while the exchanges give them a way to protect against cryptocurrency volatility.
+
+==Summary==
+
+The merchant log in to its exchange website, go into "Address sources" section of it, an click on "Create a new address source".
+
+The address source creation wizard asks him questions about what to do when crypto currency is sent to this the address source. (Cryptocurrency, Market sell order, limit order of past day average etc...)
+
+The wizard will also request webhook information so the exchange can notify the payment processor when a payment is made and when it is confirmed.
+
+The merchant receives an "address source URI" which they can input inside the payment processor.
+
+An exchange compatible with the Crypto Open Exchange Protocol would reply to any HTTP POST request to this  "address source URI" returning the following information (more details in the Specification part)
+
+# A deposit address for accepting a payment.  This address will be uniquely generated for each POST request.
+# The current rate
+# Optional: If the exchange is willing to take the risk of rate fluctuation, until when this rate is guaranteed and under which conditions.
+
+<img src="bip-xxx/overview.png"></img>
+
+===Interaction===
+
+* Manny (the "merchant") wants to accept Bitcoin payments on his e-commerce website.
+* Manny chooses the payment processor "PROCCO" which has a powerful plugin for his e-commerce website.
+* Manny is based in Canada and already has an account on the exchange "MYCOIN" which supports the Crypto Open Exchange Protocol.
+* Manny connects to the exchange website, and creates a new address source.
+* In the configuration screen of the address source, for each payment sent to this address source, Manny decides to keep 30% in Bitcoin and place a market sell order for the remaining 70% of the amount.
+* Manny provides "PROCCO's" webhook endpoint that so "PROCCO" is notified when payments have been made and confirmed. 
+* "MYCOIN" creates the address source, and gives the "address source URI" to the merchant. (e.g. https://example.com/addresssources/abd29ddn92)
+* Manny copies the address source URI and goes inside "PROCCO" settings, and configures his store to use this address source URI.
+
+Now a customer, Carol, wants to order a brand new phone for 0.01 BTC on Manny's store and decides to pay in Bitcoin.
+
+* The E-Commerce website plugin requests the creation of an invoice from PROCCO. 
+* PROCCO queries the "address source URI" and retrieves the rate, the expiration of this rate and conditions.
+* PROCCO can now show the Bitcoin Payment Checkout page.
+* Carla pays.  MYCOIN sees the payment in the mempool and notifies PROCCO that a payment has been made via the webhook.
+* PROCCO updates the invoice to acknowledge that a payment has been sent.  
+* MYCOIN, under its own policy (typically after 6 confirmations), credits Manny's account of 0.01 BTC and simultaneously creates a market sell order of 0.007 BTC on behalf of Manny.   MYCOIN notifies PROCCO that the payment was confirmed and finalized via the webhook.
+* PROCCO marks the payment as paid/finalized.   Manny sees the order has been paid and processes the order as usual.
+
+==Specification==
+
+The payment processor sends a POST request to the "address source URI", the response from a Crypto Open Exchange Protocol exchange would be:
+
+If the exchange does not guarantee the rate:
+
+    {
+        "depositAddress" : "13....abd",
+        "currencyCode" : "CAD",
+        "cryptoCurrencyCode" : "BTC",
+        "rate" : "15600",
+        # When the merchant account get credited on the exchange
+        "requiredConfirmations" : blockcount
+    }
+
+
+If the exchange guarantees the rate:
+
+    {
+        "depositAddress" : "13....abd",
+        "currencyCode" : "CAD",
+        "cryptoCurrencyCode" : "BTC",
+        "rate" : "15600",
+        "requiredConfirmations" : blockcount,
+        "conditions" : 
+        {
+            # When the transaction should be seen on the blockchain to guarantee the rate
+            "receivedBefore" : timestamp,
+            # When the transaction should be confirmed on the blockchain to guarantee the rate
+            "confirmedBefore" : timestamp
+        }
+    }
+
+
+When the payment hits the mempool, the exchange sends the following POST to the processor's webhook URI:
+
+  {
+        "depositAddress" : "13....abd",
+        "cryptoAmountReceived" : "0.01",
+        "receivedTimestamp" : timestamp,
+        "rateGuarenteedInEffect" : "false",
+        # When exchange provided a guarenteed rate and the conditions were not met
+        "conditionFailure" : "Received after window"
+  }
+
+
+When the payment is considered confirmed, the exchange sends the following POST to the processor's webhook URI:
+
+  {
+        "depositAddress" : "13....abd",
+        "currencyCode" : "CAD",
+        "cryptoCurrencyCode" : "BTC",
+        "rateReceived" : "15600",
+        "cryptoAmountReceived" : "0.01",
+        "receivedTimestamp" : timestamp,
+        "confirmedTimestamp" : timestamp,
+        # When exchange provided a guarenteed rate
+        "guarenteedRateReceived" : "false",
+        # When exchange provided a guarenteed rate and the conditions were not met
+        "conditionFailure" : "Received after window"
+  }
+
+The payment processor will use the postback information to determine if the invoice is paid and to alert the merchant and customer to any issues (e.g. if the payment amount is wrong, it was sent/confirmed too late, etc).
+
+==Note on adoption==
+
+While local exchanges have incentives to implement this simple protocol, it is not strictly needed.
+
+An alternative is to develop an adapter server which expose Crypto Open Exchange Protocol endpoint and connect to underlying exchange's API.
+
+The only downside is that the rate can't be guaranteed.
+
+==Copyright==
+
+This document is dual licensed as BSD 3-clause, and Creative Commons CC0 1.0 Universal.