================================= Merchant Reference Implementation ================================= ----------------------- Architectural Overview ----------------------- The merchant reference implementationis divided into 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. ------------------------------ The Frontent HTTP API ------------------------------ .. http:get:: /taler/contract Triggers the contract generation. Note that the URL may differ between merchants. **Request:** The request depends entirely on the merchant implementation. **Response** :status 200 OK: The request was successful. The body contains an :ref:`offer `. :status 400 Bad Request: Request not understood. :status 500 Internal Server Error: In most cases, some error occurred while the backend was generating the contract. For example, it failed to store it into its database. ------------------------------ The Merchant Backend HTTP API ------------------------------ The following API are made available by the merchant's `backend` to the merchant's `frontend`. .. http:post:: /hash-contract Ask the backend to compute the hash of the `contract` given in the POST's body (the full contract should be the value of a JSON field named `contract`). This feature allows frontends to verify that names of resources which are going to be sold are actually `in` the paid cotnract. Without this feature, a malicious wallet can request resource A and pay for resource B without the frontend being aware of that. **Response** :status 200 OK: hash succesfully computed. The returned value is a JSON having one field called `hash` containing the hashed 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:: /contract Ask the backend to add some missing (mostly related to cryptography) information to the contract. **Request:** 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. **Response** :status 200 OK: The backend has successfully created the contract. :status 400 Bad Request: Request not understood. The JSON was invalid. Possibly due to some error in formatting the JSON by the `frontend`. On success, the `frontend` should pass this response verbatim to the wallet. .. http:post:: /pay Asks the `backend` to execute the transaction with the mint and deposit the coins. **Request:** The `frontend` passes the :ref:`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 **Response:** :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. :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. The `backend` will return verbatim the error codes received from the mint's :ref:`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.