Extend API to support refunds

1 files changed, 103 insertions, 36 deletions

diff --git a/api-merchant.rst b/api-merchant.rst
index 339498d0..6375d4c2 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -1,22 +1,28 @@
 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 Merchant API serves as a protocol interface for the 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.  Futhermore, it is assumed that the merchant's server is cooperating *i.e*
+does not repudiate on received requests.
 
 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.
+information are provided in the contract.  The customer can either agree or
+disagree with the contract.  If there is a disagreement between the merchant and
+the customer, the customer can choose to abort the protocol by not participating
+int the furthur steps.  If the customer chooses to agree, the aggrement is sent
+to the merchant as a ``deposit permission`` which effectively is also a
+confirmation made by the customer to pay the merchant the sum mentioned in the
+contract.  The merchant then submits this deposit permission at the mint to
+verify its validity.  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
@@ -35,10 +41,19 @@ reached.
 
 The thrid type of interactions allows probablistic spending.  `To be done.`
 
+Contract retraction/returns/refunds: It is common for merchants to provide a
+retraction period where the customer can evaluate the products and return them
+for a refund.  To facilitate such interactions, our protocol allows merchants to
+provide a retraction period in the contract.  During the retraction period a
+customer can retract a previously made contract with the merchant and obtain a
+``retract permission`` from the merchant.  The customer, before the end of the
+retraction period, can submit the retract permission to the mint to obtain a
+refund.
+
 The following are the API made available by the merchant:
 
-.. http:GET:: /contract
-.. http:POST:: /contract
+.. http:GET:: /offer
+.. http:POST:: /offer
 
    Ask the merchant to prepare a contract.  The request parameters are specific
    to the merchant's implementation, however, they are recommended to contain
@@ -51,13 +66,20 @@ The following are the API made available by the merchant:
 
    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
+   :>json string transaction_id: A string representing the transaction identifier.
+   :>json integer expiry: The timestamp after which this contract expires.
+   :>json object amount: Price of the contract as a Denomination object.
+   :>json integer retraction_period: The period of time expressed in seconds
+     during which the customer can retract this contract and thus can claim the
+     coins spent for this contract by refreshing them at the mint.  The
+     retraction period starts from the moment the customer has signed the
+     contract.  During the retraction period, the mint withholds the contract's
+     money from being transferred to the merchant.
+   :>json string description: The contract description as string.
+   :>json 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`.
+   :>json string msig: Signature of the merchant over the fields `transaction_id`,
+     `expiry`, `amount`, `retraction_period`, `description`, `H_wire`.
 
    **Failure response**
 
@@ -67,27 +89,33 @@ The following are the API made available by the merchant:
    It is also possible to receive other error status codes depending on the
    merchant's implementation.
 
-.. http:GET:: /deposit
+.. http:POST:: /pay
 
-   Send a ``deposit-permission`` JSON object to the merchant.  The object should
-   contain the following fields:
+   Agree with the previously obtained contract and pay the merchant by signing
+   the contract with a coin.  The request is a JSON object containing 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"`
+   :<json string coin_pub: The coin's public key.
+   :<json string mint_pub: The public key of the mint from where the coin is obtained.
+   :<json string denom_pub: Denomination key with which the coin is signed
+   :<json string ubsig: Mint's unblinded signature of the coin
+   :<json string 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
+   :<json string transaction_id: The transaction identifier obtained from the contract.
+   :<json object 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`.
+   :<json string merchant_pub: The public key of the merchant.
+   :<json integer retract_until: The timestamp until which the customer can retract the
+     contract and claim for a refund.  This should be generated by the customer
+     by adding the retraction period mentioned in the contract to the present
+     UTC time in seconds.
+   :<json string H_a: The hash of the contract.
+   :<json string H_wire: The hash of the merchant's payment information.
+   :<json string csig: The signature with the coin's private key over the parameters
+     `type`, `transaction_id`, `amount`, `merchant_pub`, `retract_until`,
+     `H_a` and, `H_wire`.
 
    **Success Response**
 
@@ -107,7 +135,46 @@ The following are the API made available by the merchant:
    :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>`.
+                failure response objects from the :ref:`Mint
+                API:deposit<deposit>`.
+
+.. _retract:
+.. http:POST:: /retract
+
+   Retract a previously made contract with the merchant.  The request should
+   contain a JSON object with the following fields:
+
+   :<json string status: the string constant `"RETRACT"`
+   :<json string transaction_id: The transaction identifier of the contract to
+                                 retract.
+   :<json string merchant_pub: The public key of the merchant.
+   :<json string csig: The signature over the fields `transaction_id` and
+                       `merchant_pub` with the private key of the coin used to
+                       previously sign the contract.
+
+   **Success Response**
+
+   :status 200 OK: The contract has been successfully retracted.
+
+   The response contains a JSON object with the following fields.  The customer
+   then has to send this object as part of the refresh request to claim the
+   refund (See: :ref:`Mint API:refresh<refresh>`)
+
+   :>json string status: the string constanst `"RETRACT"`
+   :>json string transaction_id: The identifier of the transaction that is
+                                 retracted
+   :>json string merchant_pub: The public key of the merchant whose contract
+                               is retracted
+   :>json string csig: The signature of the coin submpitted by the merchant's
+                       customer over the fields `transaction_id` and
+                       `merchant_pub`
+   :>json string msig: The signature of the merchant over the fields `status`
+                       and `transaction_id`
+
+   **Failure Response**
+
+   :status 400: Request not understood
+   :status 404: Invalid contract
+   :status 403: The contract's retraction period has expired
 
 Other interactions tbd..