summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--dev-merchant.rst74
-rw-r--r--glossary.rst15
-rw-r--r--integration-general.rst57
-rw-r--r--integration-merchant.rst5
4 files changed, 151 insertions, 0 deletions
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 <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.
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 <http://www.w3.org/TR/DOM-Level-3-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
+==================================
+
+