From 67232ff07977b83288577b060e0f1bab4bb27293 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 7 Jan 2020 20:22:46 +0100 Subject: restructure bank docs, update wire plugin HTTP API --- taler-bank-manual.rst | 177 +++++++++----------------------------------------- 1 file changed, 29 insertions(+), 148 deletions(-) (limited to 'taler-bank-manual.rst') diff --git a/taler-bank-manual.rst b/taler-bank-manual.rst index 4c1b5730..bb64961a 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 wallet. -.. _Reference: +Headless Testing API Reference +============================== -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. -``create-reserve`` - 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 + https://docs.djangoproject.com/en/2.2/ref/contrib/auth/#django.contrib.auth.models.User.username + for the accepted character set. - - ``X-Taler-Amount``: The amount that will be transferred to the - reserve. +**Details** - - ``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. - -``confirm-reserve`` - 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 -merchant. - -Withdraw -~~~~~~~~ - -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 -https://docs.taler.net/api/api-exchange.html#administrative-api-bank-transactions. - -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. -- cgit v1.2.3