path: root/taler-bank-manual.rst
diff options
authorFlorian Dold <>2020-01-07 20:22:46 +0100
committerFlorian Dold <>2020-01-07 20:22:46 +0100
commit67232ff07977b83288577b060e0f1bab4bb27293 (patch)
treef983e2feffc770074527b87d87d099a6e3d40c89 /taler-bank-manual.rst
parent81d6d8b3df0a5c760d35a24a38877c48303bc7a5 (diff)
restructure bank docs, update wire plugin HTTP API
Diffstat (limited to 'taler-bank-manual.rst')
1 files changed, 29 insertions, 148 deletions
diff --git a/taler-bank-manual.rst b/taler-bank-manual.rst
index 4c1b573..bb64961 100644
--- a/taler-bank-manual.rst
+++ b/taler-bank-manual.rst
@@ -27,164 +27,45 @@ local/regional currency. Finally, “real” banks might use it as a
reference implementation for a tight integration with the GNU Taler
-.. _Reference:
+Headless Testing API Reference
+The demonstrator bank offers the following APIs to allow automated testing. These APIs should
+be switched off during a production deployment.
-.. _Bank_002dWallet-interaction:
-Bank-Wallet interaction
+.. _bank-register:
+.. http:post:: /register
-The HTTP status code ``202 Accepted`` can be used by the bank website to
-trigger operations in the user agent. The operation is determined by the
-``X-Taler-Operation`` header. The following operations are understood:
+ This API provides programmatic user registration at the bank.
- Ask the Taler wallet to create a reserve and call back the bank with
- the reserve public key. The following headers are mandatory:
+ **Request** The body of this request must have the format of a
+ `BankRegistrationRequest`.
- - ``X-Taler-Callback-Url``: URL that the wallet will visit when the
- reserve was created and the user has selected an exchange.
+ **Response**
- - ``X-Taler-Wt-Types``: JSON-encoded array of wire transfer types
- that this bank supports.
+ :status 200 OK:
+ The new user has been correctly registered.
+ :status 409 Conflict:
+ The username requested by the client is not available anymore.
+ :status 406 Not Acceptable:
+ Unacceptable characters were given for the username. See
+ for the accepted character set.
- - ``X-Taler-Amount``: The amount that will be transferred to the
- reserve.
- - ``X-Taler-Sender-Wire``: JSON-encoded wire account details of the
- sender, that is the user that is currently logged in with the bank
- and creates the reserve.
+.. ts:def:: BankRegistrationRequest
- The following header is optional:
+ interface BankRegistrationRequest {
+ // Username to use for registration; max length is 150 chars.
+ username: string;
- - ``X-Taler-Suggested-Exchange``: Exchange that the bank recommends
- the customer to use. Note that this is a suggestion and can be
- ignored by the wallet or changed by the user.
+ // Password to associate with the username. Any characters and
+ // any length are valid; next releases will enforce a minimum length
+ // and a safer characters choice.
+ password: string;
+ }
- On successful reserve creation, the wallet will navigate to the
- callback URL (effectively requesting it with a GET) with the
- following additional request parameters:
- - ``exchange``: The URL of the exchange selected by the user
- - ``wire_details``: The wire details of the exchange.
- - ``reserve_pub``: The reserve public key that the bank should
- transmit to the exchange when transmitting the funds.
- To secure the operation, the (demo) bank then shows a "CAPTCHA page"
- – a real bank would instead show some PIN entry dialog or similar
- security method – where the customer can finally prove she their
- identity and thereby confirm the withdraw operation to the bank.
- Afterwards, the bank needs to confirm to the wallet that the user
- completed the required steps to transfer funds to an exchange to
- establish the reserve identified by the ``X-Taler-Reserve-Pub``
- header.
- This does not guarantee that the reserve is already created at the
- exchange (since the actual money transfer might be executed
- asynchronously), but it informs that wallet that it can start polling
- for the reserve.
-.. _Bank_002dExchange-interaction:
-Bank-Exchange interaction
-The interaction between a bank and the exchange happens in two
-situations: when a wallet withdraws coins, and when the exchange pays a
-Once a withdrawal operation with the wallet has been confirmed, the the
-bank must wire transfer the withdrawn amount from the customer account
-to the exchange’s. After this operation is done, the exchange needs to
-be informed so that it will create the reserve.
-For the moment, the bank will use the exchange’s ``/admin/add/incoming``
-API, providing those arguments it got along the ``X-Taler-Callback-Url``
-URL. (In the future, the exchange will poll for this information.)
-However, the bank will define two additional values for this API:
-``execution_date`` (a operation’s timestamp), and ``transfer_details``
-(just a "seed" to make unique the operation). See
-The polling mechanism is possbile thanks to the ``/history`` API
-provided by the bank. The exchange will periodically use this API to see
-if it has received new wire transfers; upon receiving a new wire
-transfer, the exchange will automatically create a reserve and allow the
-money sender to withdraw.
-``GET /history``
- Ask the bank to return a list of money transactions related to a
- caller’s bank account.
- - ``auth`` a string indicating the authentication method to use;
- only ``"basic"`` value is accepted so far. The username and
- password credentials have to be sent along the HTTP request
- headers. Namely, the bank will look for the following two headers:
- ``X-Taler-Bank-Username`` and ``X-Taler-Bank-Password``, which
- will contain those plain text credentials.
- - ``delta`` returns the first ``N`` records younger (older) than
- ``start`` if ``+N`` (``-N``) is specified.
- - ``start`` according to delta, only those records with row id
- strictly greater (lesser) than start will be returned. This
- argument is optional; if not given, delta youngest records will be
- returned.
- - ``direction`` optional argument taking values debit or credit,
- according to the caller willing to receive both incoming and
- outgoing, only outgoing, or only incoming records
- - ``account_number`` optional argument indicating the bank account
- number whose history is to be returned. If not given, then the
- history of the calling user will be returned
-Exchange pays merchant
-To allow the exchange to send payments to a merchant, the bank exposes
-the ``/admin/add/incoming`` API to exchanges.
-``POST /admin/add/incoming``
- Ask the bank to transfer money from the caller’s account to the
- receiver’s.
- - ``auth`` a string indicating the authentication method to use;
- only ``"basic"`` value is accepted so far. The username and
- password credentials have to be sent along the HTTP request
- headers. Namely, the bank will look for the following two headers:
- ``X-Taler-Bank-Username`` and ``X-Taler-Bank-Password``, which
- will contain those plain text credentials.
- - ``amount`` a JSON object complying to the Taler amounts layout.
- Namely, this object must contain the following fields: ``value``
- (number), ``fraction`` (number), and ``currency`` (string).
- - ``exchange_url`` a string indicating the calling exchange base
- URL. The bank will use this value to define wire transfers subject
- lines.
- - ``wtid`` a alphanumeric string that uniquely identifies this
- transfer at the exchange database. The bank will use this value
- too to define wire transfers subject lines. Namely, subject lines
- will have the following format: ``'wtid exchange_url'``.
- - ``debit_account`` number indicating the exchange bank account.
- NOTE: this field is currently ignored, as the bank can retrieve
- the exchange account number from the login credentials. However,
- in future release, an exchange could have multiple account at the
- same bank, thereby it will have the chance to specify any of them
- in this field.
- - ``credit_account`` bank account number that will receive the
- transfer. Tipically the merchant account number.