summaryrefslogtreecommitdiff
path: root/api-bank.rst
diff options
context:
space:
mode:
authorFlorian Dold <florian.dold@gmail.com>2019-08-29 13:02:55 +0200
committerFlorian Dold <florian.dold@gmail.com>2019-08-29 13:02:55 +0200
commitba9335ec4c3578fdebfbec3072396bcda29d3425 (patch)
tree6d44f540797cba9ed77f28548714ff874141da66 /api-bank.rst
parentc3a6698c48f315e124bfd89bbb98564966f89434 (diff)
downloaddocs-ba9335ec4c3578fdebfbec3072396bcda29d3425.tar.gz
docs-ba9335ec4c3578fdebfbec3072396bcda29d3425.tar.bz2
docs-ba9335ec4c3578fdebfbec3072396bcda29d3425.zip
initial rough import of other docs
Diffstat (limited to 'api-bank.rst')
-rw-r--r--api-bank.rst392
1 files changed, 0 insertions, 392 deletions
diff --git a/api-bank.rst b/api-bank.rst
deleted file mode 100644
index 07de819..0000000
--- a/api-bank.rst
+++ /dev/null
@@ -1,392 +0,0 @@
-..
- This file is part of GNU TALER.
-
- Copyright (C) 2014, 2015, 2016, 2017 Taler Systems SA
-
- 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 General Public License for more details.
-
- You should have received a copy of the GNU General Public License along with
- TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-
- @author Marcello Stanisci
- @author Christian Grothoff
-
-=========
-Bank API
-=========
-
-This API provides programmatic user registration at the bank.
-
-.. _bank-register:
-.. http:post:: /register
-
-**Request** The body of this request must have the format of a `BankRegistrationRequest`_.
-
-**Response**
-
-: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 https://docs.djangoproject.com/en/2.2/ref/contrib/auth/#django.contrib.auth.models.User.username for the accepted character set.
-
-**Details**
-
-.. _BankRegistrationRequest:
-.. code-block:: tsref
-
- interface BankRegistrationRequest {
-
- // Username to use for registration; max length is 150 chars.
- username: string;
-
- // 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;
- }
-
-
-This API provides programmatic withdrawal of cash via Taler to all the
-users registered at the bank. It triggers a wire transfer from the client
-bank account to the exchange's.
-
-.. _bank-register:
-.. http:post:: /taler/withdraw
-
-**Request** The body of this request must have the format of a `BankTalerWithdrawRequest`_.
-
-**Response**
-
-:status 200 OK: The withdrawal was correctly initiated, therefore the exchange received the payment. A `BankTalerWithdrawResponse`_ object is returned.
-:status 406 Not Acceptable: the user does not have sufficient credit to fulfill their request.
-:status 404 Not Found: The exchange wire details did not point to any valid bank account.
-
-**Details**
-
-.. _BankTalerWithdrawRequest:
-.. code-block:: tsref
-
- interface BankTalerWithdrawRequest {
-
- // Authentication method used
- auth: BankAuth;
-
- // Amount to withdraw.
- amount: Amount;
-
- // Reserve public key.
- reserve_pub: string;
-
- // Exchange bank details specified in the 'payto'
- // format. NOTE: this field is optional, therefore
- // the bank will initiate the withdrawal with the
- // default exchange, if not given.
- exchange_wire_details: string;
- }
-
-.. _BankTalerWithdrawResponse:
-.. code-block:: tsref
-
- interface BankTalerWithdrawResponse {
-
- // Sender account details in 'payto' format.
- sender_wire_details: string;
-
- // Exchange base URL. Optional: only returned
- // if the user used the default exchange.
- exchange_url: string;
- }
-
-This API allows one user to send money to another user, within the same "test"
-bank. The user calling it has to authenticate by including his credentials in the
-request.
-
-.. _bank-deposit:
-.. http:post:: /admin/add/incoming
-
-**Request:** The body of this request must have the format of a `BankDepositRequest`_.
-
-**Response:**
-
-:status 200 OK: The request has been correctly handled, so the funds have been transferred to the recipient's account. The body is a `BankDepositDetails`_.
-:status 400 Bad Request: The bank replies a `BankError`_ object.
-:status 406 Not Acceptable: The request had wrong currency; the bank replies a `BankError`_ object.
-
-**Details:**
-
-.. _BankDepositDetails:
-.. code-block:: tsref
-
- interface BankDepositDetails {
-
- // Timestamp related to the transaction being made.
- timestamp: Timestamp;
-
- // Row id number identifying the transaction in the bank's
- // database.
- row_id: number;
- }
-
-.. _BankDepositRequest:
-.. code-block:: tsref
-
- interface BankDepositRequest {
-
- // Authentication method used
- auth: BankAuth;
-
- // JSON 'amount' object. The amount the caller wants to transfer
- // to the recipient's count
- amount: Amount;
-
- // Exchange base URL, used to perform tracking requests against the
- // wire transfer ID. Note that in the actual bank wire transfer,
- // the schema may have to be encoded differently, i.e.
- // "https://exchange.com/" may become "https exchange.com" due to
- // character set restrictions. It is the responsibility of the
- // wire transfer adapter to properly encode/decode the URL.
- // Payment service providers must ensure that their URL is short
- // enough to fit together with the wire transfer identifier into
- // the wire transfer subject of their respective banking system.
- exchange_url: string;
-
- // The subject of this wire transfer.
- subject: string;
-
- // The sender's account identificator. NOTE, in the current stage
- // of development this field is _ignored_, as it's always the bank account
- // of the logged user that plays as the "debit account".
- // In future releases, a logged user may specify multiple bank accounts
- // of her/his as the debit account.
- debit_account: number;
-
- // The recipient's account identificator
- credit_account: number;
-
- }
-
-.. _BankAuth:
-.. _tsref-type-BankAuth:
-.. code-block:: tsref
-
- interface BankAuth {
-
- // authentication type. At this stage of development,
- // only value "basic" is accepted in this field.
- // The credentials must be indicated in the following HTTP
- // headers: "X-Taler-Bank-Username" and "X-Taler-Bank-Password".
- type: string;
- }
-
-
-.. _BankError:
-.. code-block:: tsref
-
- interface BankError {
-
- // Human readable explanation of the failure.
- error: string;
-
- // Numeric Taler error code (`enum TALER_ErrorCode`)
- ec: number;
-
- }
-
-
-.. http:put:: /reject
-
- Rejects an inbound transaction. This can be used by the receiver of a wire transfer to
- cancel that transaction, nullifying its effect. This basically creates a correcting
- entry that voids the original transaction. Henceforth, the /history must show
- the original transaction as "cancelled+" or "cancelled-" for creditor and debitor respectively.
- This API is used when the exchange receives a wire transfer with an invalid wire
- transfer subject that fails to decode to a public key.
-
- **Request** The body of this request must have the format of a `BankCancelRequest`_.
-
- :query auth: authentication method used. At this stage of development, only value `basic` is accepted. Note that username and password need to be given as request's headers. The dedicated headers are: `X-Taler-Bank-Username` and `X-Taler-Bank-Password`.
- :query row_id: row identifier of the transaction that should be cancelled.
- :query account_number: bank account for which the incoming transfer was made and for which `auth` provides the authentication data. *Currently ignored*, as multiple bank accounts per user are not implemented yet.
-
- .. _BankCancelRequest:
- .. code-block:: tsref
-
- interface BankCancelRequest {
-
- // Authentication method used
- auth: BankAuth;
-
- // The row id of the wire transfer to cancel
- row_id: number;
-
- // The recipient's account identificator
- credit_account: number;
-
- }
-
- **Response** In case of an error, the body is a `BankError`_ object.
-
- :status 204 No Content: The request has been correctly handled, so the original transaction was voided. The body is empty.
- :status 400 Bad Request: The bank replies a `BankError`_ object.
- :status 404 Not Found: The bank does not know this rowid for this account.
-
-
-.. http:get:: /history-range
-
- Filters and returns the list of transactions in the time range specified by `start` and `end`
-
- **Request**
-
- :query auth: authentication method used. At this stage of development, only value `basic` is accepted. Note that username and password need to be given as request's headers. The dedicated headers are: `X-Taler-Bank-Username` and `X-Taler-Bank-Password`.
- :query start: unix timestamp indicating the oldest transaction accepted in the result.
- :query end: unix timestamp indicating the youngest transaction accepted in the result.
- :query direction: argument taking values `debit` or `credit`, according to the caller willing to receive both incoming and outgoing, only outgoing, or only incoming records. Use `both` to return both directions.
- :query cancelled: argument taking values `omit` or `show` to filter out rejected transactions
- :query account_number: bank account whose history is to be returned. *Currently ignored*, as multiple bank accounts per user are not implemented yet.
- :query ordering: can be `descending` or `ascending` and regulates whether the row are returned youger-to-older or vice versa. Defaults to `descending`.
-
-
- **Response**
-
- :status 200 OK: JSON object whose field `data` is an array of type `BankTransaction`_.
- :status 204 No content: in case no records exist for the targeted user.
-
-
-.. http:get:: /history
-
- Filters and returns the list of transactions of the customer specified in the request.
-
- **Request**
-
- :query auth: authentication method used. At this stage of development, only value `basic` is accepted. Note that username and password need to be given as request's headers. The dedicated headers are: `X-Taler-Bank-Username` and `X-Taler-Bank-Password`.
- :query delta: returns the first `N` records younger (older) than `start` if `+N` (`-N`) is specified.
- :query 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, it defaults to "MAX_UINT64".
- :query direction: argument taking values `debit` or `credit`, according to the caller willing to receive both incoming and outgoing, only outgoing, or only incoming records. Use `both` to return both directions.
- :query cancelled: argument taking values `omit` or `show` to filter out rejected transactions
- :query account_number: bank account whose history is to be returned. *Currently ignored*, as multiple bank accounts per user are not implemented yet.
- :query ordering: can be `descending` or `ascending` and regulates whether the row are returned youger-to-older or vice versa. Defaults to `descending`.
-
-
- **Response**
-
- :status 200 OK: JSON object whose field `data` is an array of type `BankTransaction`_.
- :status 204 No content: in case no records exist for the targeted user.
-
-.. _BankTransaction:
-.. code-block:: tsref
-
- interface BankTransaction {
-
- // identification number of the record
- row_id: number;
-
- // Date of the transaction
- date: Timestamp;
-
- // Amount transferred
- amount: Amount;
-
- // "-" if the transfer was outgoing, "+" if it was
- // incoming; "cancel+" or "cancel-" if the transfer
- // was /reject-ed by the receiver.
- sign: string;
-
- // Bank account number of the other party involved in the
- // transaction.
- counterpart: number;
-
- // Wire transfer subject line.
- wt_subject: string;
-
- }
-
-..
- The counterpart currently only points to the same bank as
- the client using the bank. A reasonable improvement is to
- specify a bank URL too, so that Taler can run across multiple
- banks.
-
-------------------------
-Interactions with wallet
-------------------------
-
-A bank and a wallet need to communicate for (1) make some elements visible
-only if the wallet is installed, (2) exchange information when the user withdraws
-coins.
-
-Make elements visible.
-^^^^^^^^^^^^^^^^^^^^^^
-
-This feature works via CSS injection from the wallet. To enable it, the
-page must contain the ``<html data-taler-nojs="true">`` element, so that
-the wallet will do the injection.
-
-Whenever a element ``<x>`` needs to be visualized (hidden) if the wallet is
-installed, the special class ``taler-installed-show`` (``taler-installed-hide``)
-must be added to ``x``, as follows:
-
-* ``<x class="taler-installed-show">y</x>`` will make ``y`` visible.
-* ``<x class="taler-installed-hide">y</x>`` will make ``y`` visible.
-
-Clearly, a fallback page must be provided, which will be useful if the
-wallet is *not* installed. This special page will hide any element of
-the class ``taler-install-show``; it can be downloaded at the following
-URL: ``git://taler.net/web-common/taler-fallback.css``.
-
-Withdrawing coins.
-^^^^^^^^^^^^^^^^^^
-
-After the user confirms the withdrawal, the bank must return a `202 Accepted` response,
-along with the following HTTP headers:
-
-* ``X-Taler-Operation: create-reserve``
-* ``X-Taler-Callback-Url: <callback_url>``; this URL will be automatically visited by the wallet after the user confirms the exchange.
-* ``X-Taler-Wt-Types: '["test"]'``; stringified JSON list of supported wire transfer types (only 'test' supported so far).
-* ``X-Taler-Amount: <amount_string>``; stringified Taler-style JSON :ref:`amount <amount>`.
-* ``X-Taler-Sender-Wire: <wire_details>``; stringified WireDetails_.
-* ``X-Taler-Suggested-Exchange: <URL>``; this header is optional, and ``<URL>`` is the suggested exchange URL as given in the `SUGGESTED_EXCHANGE` configuration option.
-
-.. _WireDetails:
-.. code-block:: tsref
-
- interface WireDetails {
- type: string; // Only 'test' value admitted so far.
- bank_uri: URL of the bank.
- account_number: bank account number of the user attempting to withdraw.
- }
-
-After the user confirms the exchange to withdraw coins from, the wallet will
-visit the callback URL, in order to let the user answer some security questions
-and provide all relevant data to create a reserve.
-
-.. note::
- Currently, the bank is in charge of creating the reserve at the chosen
- exchange. In future, the exchange will "poll" its bank account and automatically
- creating a reserve whenever it receives any funds, without any bank's
- intervention.
-
-The callback URL implements the following API.
-
-.. http:get:: <callback_url>
-
- **Request**
-
- :query amount_value: integer part of the amount to be withdrawn.
- :query amount_fraction: fractional part of the amount to be withdrawn.
- :query amount_currency: currency of the amount to be withdrawn.
- :query exchange: base URL of the exchange where the reserve is to be created.
- :query reserve_pub: public key of the reserve to create.
- :query exchange_wire_details: stringification of the chosen exchange's WireDetails_.
-
- **Response**
-
- Because the wallet is not supposed to take action according to this response,
- the bank implementers are not required to return any particular status code here.
-
- For example, our demonstrator bank always redirects the browser to the user's
- profile page and let them know the outcome via a informational bar.