From c274498534e64226cb6face265452278ad76402c Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 12 Jan 2016 15:43:20 +0100 Subject: missing .rst files --- dev-merchant.rst | 74 ++++++++++++++++++++++++++++++++++++++++++++++++ glossary.rst | 15 ++++++++++ integration-general.rst | 57 +++++++++++++++++++++++++++++++++++++ integration-merchant.rst | 5 ++++ 4 files changed, 151 insertions(+) create mode 100644 dev-merchant.rst create mode 100644 glossary.rst create mode 100644 integration-general.rst create mode 100644 integration-merchant.rst diff --git a/dev-merchant.rst b/dev-merchant.rst new file mode 100644 index 00000000..773d05c1 --- /dev/null +++ b/dev-merchant.rst @@ -0,0 +1,74 @@ +================================= +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 Merchant Backend HTTP 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 ` 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 ` 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. diff --git a/glossary.rst b/glossary.rst new file mode 100644 index 00000000..32bd66f1 --- /dev/null +++ b/glossary.rst @@ -0,0 +1,15 @@ +============== +Taler Glossary +============== + +.. glossary:: + + wallet + EXPLAIN + + reserve + EXPLAIN + + bank + EXPLAIN + diff --git a/integration-general.rst b/integration-general.rst new file mode 100644 index 00000000..c73e0f87 --- /dev/null +++ b/integration-general.rst @@ -0,0 +1,57 @@ +================================ +Taler Wallet Website Integration +================================ + +Websites (such as banks and online shops) can communicate with +the Taler wallet by a standardized protocol. + +From a technical perspective, the Taller wallet communicates with +the website by sending and receiving `DOM events `_ +on the bank website's ``HTMLDocument``. + +DOM events used by Taler have the prefix ``taler-``. + +.. _communication: + +---------------------- +Communication Example +---------------------- + +The bank website can send the event ``taler-XYZ`` with the event data ``eventData``. +to the wallet with the following JavaScript code: + +.. sourcecode:: javascript + + const myEvent = new CustomEvent("taler-XYZ", eventData); + document.dispatchEvent(myEvent); + +Events can be received by installing a listener: + + +.. sourcecode:: javascript + + function myListener(talerEvent) { + // handle event here! + } + document.addEventListener("taler-XYZ", myListener); + + +-------------------- +Normalized Base URLs +-------------------- + +Mints and merchants have a base URL for their service. This URL *must* be in a +canonical form when it is stored (e.g. in the wallet's database) or transmitted +(e.g. to a bank page). + +1. The URL must be absolute. This implies that the URL has a schema. +2. The path component of the URL must end with a slash. +3. The URL must not contain a fragment or query. + +When a user enters a URL that is, technically, relative (such as "alice.example.com/mint"), wallets +*may* transform it into a canonical base URL ("http://alice.example.com/mint/"). Other components *should not* accept +URLs that are not canonical. + +Rationale: Joining non-canonical URLs with relative URLs (e.g. "mint.example.com" with "reserve/status") +results in different and slightly unexpected behavior in some URL handling libraries. +Canonical URLs give more predictable results with standard URL joining. diff --git a/integration-merchant.rst b/integration-merchant.rst new file mode 100644 index 00000000..a3ca1287 --- /dev/null +++ b/integration-merchant.rst @@ -0,0 +1,5 @@ +================================== +Interaction with merchant websites +================================== + + -- cgit v1.2.3