1 files changed, 113 insertions, 0 deletions
diff --git a/api-merchant.rst b/api-merchant.rst
new file mode 100644
index 00000000..339498d0
--- /dev/null
+++ b/api-merchant.rst
@@ -0,0 +1,113 @@
+The Merchant JSON API
+=====================
+
+The Merchant API serves the protocol interactions between a customer and a
+merchant.  The protocol allows the customer and the merchant to agree upon a
+contract and for the customer to spend coins according to the contract at the
+merchant.  It should be noted that the interactions are strictly one way: The
+customer *always* initiates the requests by contacting the merchant.  It is also
+assumed that the customer knows the merchant's public key.
+
+The protocol allows for three different type of interactions.  In the first type
+of interaction, which we refer to as *direct deposit*, an interested customer
+asks the merchant to provide a ``contract`` for the merchant's services or
+products.  Details about the services or products and the merchant's payment
+information are provided in the contract.  The customer then agrees upon one of
+these contracts by giving the the merchant a ``deposit permission``.  The
+merchant then submits this deposit permission at the mint for verification.
+Upon successful verification, the merchant delivers the promised services or
+products.
+
+The second type of interaction, *incremental deposit*, allows the merchant to
+charge the customer incrementally.  This is useful for subscription based
+e-commerce systems.  Examples for such systems are app stores and news websites.
+The idea here is that the merchant will be assured that he will receive a
+certain amount of money from the transaction, and then he can charge small
+amounts over the assured amount without contacting the mint.  In these
+interactions, the customer asks merchant to make an ``offer`` for the
+subscription by specifying the maximum amount the merchant may charge during the
+interaction.  The customer conveys his acceptance of the offer by sending a
+``lock permission`` to the merchant.  The merchant asks the mint to verify the
+lock permission and if verified successfully, the customer then obtains a
+contract from the merchant and the first type interaction follows.  The customer
+can then obtain further contracts until the maximum amount made in the offer is
+reached.
+
+The thrid type of interactions allows probablistic spending.  `To be done.`
+
+The following are the API made available by the merchant:
+
+.. http:GET:: /contract
+.. http:POST:: /contract
+
+   Ask the merchant to prepare a contract.  The request parameters are specific
+   to the merchant's implementation, however, they are recommended to contain
+   information required for the merchant to identify which product or service
+   the customer is interested int.
+
+   **Success Response**
+
+   :status 200 OK: The request was successful.
+
+   The merchant responds with a JSON object containing the following fields:
+
+   * `transaction_id`: A string representing the transaction identifier.
+   * `expiry`: The timestamp after which this contract expires.
+   * `amount`: Price of the contract as a Denomination object.
+   * `description`: The contract description as string.
+   * `H_wire`: The hash of a JSON object containing the merchant's payment
+     information.  See :ref:`wireformats`.
+   * `msig`: Signature of the merchant over the fields `m`, `t`, `f`, `a`, `H_wire`.
+
+   **Failure response**
+
+   :status 400: Request not understood.
+   :status 404: No products or services given in the request were found.
+
+   It is also possible to receive other error status codes depending on the
+   merchant's implementation.
+
+.. http:GET:: /deposit
+
+   Send a ``deposit-permission`` JSON object to the merchant.  The object should
+   contain the following fields:
+
+   * `coin_pub`: The coin's public key.
+   * `mint_pub`: The public key of the mint from where the coin is obtained.
+   * `denom_pub`: Denomination key with which the coin is signed
+   * `ubsig`: Mint's unblinded signature of the coin
+   * `type`: the string constant `"DIRECT_DEPOSIT"` or `"INCREMENTAL_DEPOSIT"`
+     respectively for direct deposit or incremental deposit type of interaction.
+   * `transaction_id`: The transaction identifier obtained from the contract.
+   * `amount`: The amount to be deposited as a Denomination object.  Its value should
+     be less than or equal to the coin's face value.  Additionally, for direct
+     deposit type of interactions, this should be equal to the amount stated in
+     the contract.
+   * `merchant_pub`: The public key of the merchant.
+   * `H_a`: The hash of the contract.
+   * `H_wire`: The hash of the merchant's payment information.
+   * `csig`: The signature with the coin's private key over the parameters
+     `type`, `m`, `f`, `M`, `H_a` and, `H_wire`.
+
+   **Success Response**
+
+   :status 200 OK: The deposit permission is successful.
+
+   It is left upto the merchant's implementation to carry over the process of
+   fulfilling the agreed contract `a` from here.  For example, for services or
+   products which can be served through HTTP, this response could contain them.
+
+   **Failure Response**
+
+   :status 400: Request not understood.
+   :status 404: The merchant does not entertain this type of interaction.  Try
+                another one.
+   :status 403: The request doesn't comply to the contract provided.  The
+                request should not be repeated.
+   :status 403: The deposit operation has failed because the coin has previously
+                been deposited or it has been already refreshed; the request
+                should not be repeated again.  The response body contains the
+                failure response objects from the :ref:`Mint API deposit
+                request<deposit>`.
+
+Other interactions tbd..