summaryrefslogtreecommitdiff
path: root/api-merchant.rst
diff options
context:
space:
mode:
authorFlorian Dold <florian.dold@gmail.com>2016-01-12 15:37:11 +0100
committerFlorian Dold <florian.dold@gmail.com>2016-01-12 15:37:11 +0100
commitbea5cde2dae8e35365844bf39ea927464c1f9cad (patch)
tree2c1b08cd3e84f2a11aa653ac7af65e272c88b498 /api-merchant.rst
parent9bb9486e8c4dc0efdfada7674e26db04c2c7df55 (diff)
downloaddocs-bea5cde2dae8e35365844bf39ea927464c1f9cad.tar.gz
docs-bea5cde2dae8e35365844bf39ea927464c1f9cad.tar.bz2
docs-bea5cde2dae8e35365844bf39ea927464c1f9cad.zip
Restructuring
Diffstat (limited to 'api-merchant.rst')
-rw-r--r--api-merchant.rst108
1 files changed, 18 insertions, 90 deletions
diff --git a/api-merchant.rst b/api-merchant.rst
index 752b167..c61a6df 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -1,12 +1,13 @@
-================
-The Merchant API
-================
+=====================
+The Merchant HTTP API
+=====================
-This Merchant API defines the
-interactions between a browser-based wallet and an HTTP-based RESTful 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
-proposed by the merchant.
+The merchant API defines
+
+This Merchant API defines the interactions between a browser-based wallet and
+an HTTP-based RESTful 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 proposed by the merchant.
It is assumed that the browser has a secure and possibly
customer-anonymizing channel to the merchant, typically by using the
@@ -23,28 +24,9 @@ is expected to check that the time of his machine is approximately
correct.
------------------------
-Architecture's Overview
------------------------
-
-In our settlement, the "merchant" is divided in two independent
-compontents, the `frontend` and the `backend`.
-
-The `frontend` is the existing shopping portal of the merchant.
-The architecture tries to minimize the amount of modifications necessary
-to the `frontend` as well as the trust that needs to be placed into the
-`frontend` logic. Taler requires the frontend to facilitate two
-JSON-based interactions between the wallet and the `backend`, and
-one of those is trivial.
-
-The `backend` is a standalone C application intended to implement all
-the cryptographic routines required to interact with the Taler wallet
-and a Taler mint.
-
-
-+++++++++++++++++++++++++++++
+-----------------------------
Wallet-Frontend communication
-+++++++++++++++++++++++++++++
+-----------------------------
Taler's wallet is designed to notify the user when a certain webpage
is offering Taler as a payment option. It does so by simply changing the color of
@@ -87,9 +69,9 @@ A precise specification and sample code for implementing the signalling
is provided in the dedicated :ref:`section <message-passing-ref>`.
-++++++++++++++++++++++++++++++
+------------------------------
Frontend-Backend communication
-++++++++++++++++++++++++++++++
+------------------------------
To create a contract, the `frontend` needs to generate the body of a
`contract` in JSON format. This `proposition` is then signed by the
@@ -106,16 +88,16 @@ responsible for generating the fullfillment page.
The contract format is specified in the `contract`_ section.
-+++++++++
+---------
Encodings
-+++++++++
+---------
Data such as dates, binary blobs, and other useful formats, are encoded as described in :ref:`encodings-ref`.
.. _contract:
Contract
---------
+^^^^^^^^
A `contract` is a JSON object having the following structure, which is returned as a
successful response to the following two calls:
@@ -222,9 +204,9 @@ Wallet-Frontend
.. _message-passing-ref:
-+++++++++++++++++++
+-------------------
Messagging protocol
-+++++++++++++++++++
+-------------------
In order to reach mutual acknowledgement, and to avoid signaling loops,
we define two interactions. One is initiated by the HTML page inquiring
@@ -427,58 +409,4 @@ cookies to identify the shopping session.
The error codes and data sent to the wallet are a mere copy of those gotten from the mint when attempting to pay. The section about :ref:`deposit <deposit>` explains them in detail.
-----------------
-Frontend-Backend
-----------------
-
-+++++++++++++++
-The RESTful API
-+++++++++++++++
-
-The following API are made available by the merchant's `backend` to the merchant's `frontend`.
-
-.. http:post:: /contract
-
- Ask the backend to add some missing (mostly related to cryptography) information to the contract.
-
- :reqheader Content-Type: application/json
-
- The `proposition` that is to be sent from the frontend is a `contract` object without the fields
-
- * `merchant_pub`
- * `mints`
- * `H_wire`
-
- The `backend` then completes this information based on its configuration.
-
- **Success Response**
-
- :status 200 OK: The backend has successfully created the contract.
- :resheader Content-Type: application/json
-
- The `frontend` should pass this response verbatim to the wallet.
-
- **Failure Responses: Bad contract**
-
- :status 400 Bad Request: Request not understood. The JSON was invalid. Possibly due to some error in formatting the JSON by the `frontend`.
-
-.. http:post:: /pay
-
- Asks the `backend` to execute the transaction with the mint and deposit the coins.
-
- :reqheader Content-Type: application/json
-
- The `frontend` passes the :ref:`deposit permission <deposit-permission>` received from the wallet, by adding the fields `max_fee`, `amount` (see :ref:`contract`) and optionally adding a field named `edate`, indicating a deadline by which he would expect to receive the bank transfer for this deal
-
- **Success Response: OK**
-
- :status 200 OK: The mint accepted all of the coins. The `frontend` should now fullfill the contract. This response has no meaningful body, the frontend needs to generate the fullfillment page.
-
- **Failure Responses: Bad mint**
-
- :status 400 Precondition failed: The given mint is not acceptable for this merchant, as it is not in the list of accepted mints and not audited by an approved auditor.
-
-
- **Failure Responses: Mint trouble**
- The `backend` will return verbatim the error codes received from the mint's :ref:`deposit <deposit>` API. If the wallet made a mistake, like by double-spending for example, the `frontend` should pass the reply verbatim to the browser/wallet. This should be the expected case, as the `frontend` cannot really make mistakes; the only reasonable exception is if the `backend` is unavailable, in which case the customer might appreciate some reassurance that the merchant is working on getting his systems back online.