summaryrefslogtreecommitdiff
path: root/impl-merchant.rst
blob: 7756a097592c16a7a894c6ad99dbb062de130deb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
..
  This file is part of GNU TALER.
  Copyright (C) 2014, 2015, 2016 INRIA
  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU General Public License as published by the Free Software
  Foundation; either version 2.1, or (at your option) any later version.
  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
  You should have received a copy of the GNU Lesser General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>

  @author Marcello Stanisci
  @author Florian Dold

=================================
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 exchange.



------------------------------
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 <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`
  * `exchanges`
  * `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 exchange and deposit the coins.

  **Request:**

  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

  **Response:**

  :status 200 OK:
    The exchange 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 exchange is not acceptable for this merchant, as it is not in the
    list of accepted exchanges and not audited by an approved auditor.


  The `backend` will return verbatim the error codes received from the exchange'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.