diff options
Diffstat (limited to 'api-merchant.rst')
| -rw-r--r-- | api-merchant.rst | 108 |
1 files changed, 18 insertions, 90 deletions
diff --git a/api-merchant.rst b/api-merchant.rst index 752b167f..c61a6df7 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. |