[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: restructure bank docs, update wire p
|
From: |
gnunet |
|
Subject: |
[taler-docs] branch master updated: restructure bank docs, update wire plugin HTTP API |
|
Date: |
Tue, 07 Jan 2020 20:22:52 +0100 |
This is an automated email from the git hooks/post-receive script.
dold pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new 67232ff restructure bank docs, update wire plugin HTTP API
67232ff is described below
commit 67232ff07977b83288577b060e0f1bab4bb27293
Author: Florian Dold <address@hidden>
AuthorDate: Tue Jan 7 20:22:46 2020 +0100
restructure bank docs, update wire plugin HTTP API
---
core/api-bank.rst | 409 +-----------------------------------------
core/api-wire-plugin-bank.rst | 171 ++++++++++++++++++
core/index.rst | 1 +
taler-bank-manual.rst | 177 +++---------------
4 files changed, 206 insertions(+), 552 deletions(-)
diff --git a/core/api-bank.rst b/core/api-bank.rst
index be492b5..82ccda6 100644
--- a/core/api-bank.rst
+++ b/core/api-bank.rst
@@ -17,50 +17,14 @@
@author Marcello Stanisci
@author Christian Grothoff
-=========
-Bank API
-=========
+==============
+Taler Bank API
+==============
-.. contents:: Table of Contents
-
-
--------
-Testing
--------
-
-.. _bank-register:
-.. http:post:: /register
-
- This API provides programmatic user registration at the bank.
+This chapter describe the APIs that banks need to offer to tightly integrate
with GNU Taler.
- **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**
-
-.. ts:def:: BankRegistrationRequest
-
- interface BankRegistrationRequest {
-
- // Username to use for registration; max length is 150 chars.
- username: string;
+.. contents:: Table of Contents
- // 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;
- }
-----------
Withdrawing
@@ -117,366 +81,3 @@ Withdrawing
// if the user used the default exchange.
exchange_url: string;
}
-
----------------------------------
-Making and Rejecting Transactions
----------------------------------
-
-.. _bank-deposit:
-.. http:post:: /admin/add/incoming
-
- 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.
-
-
- **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:**
-
- .. ts:def:: BankDepositDetails
-
- 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;
- }
-
- .. ts:def:: BankDepositRequest
-
- 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;
-
- }
-
- .. ts:def:: BankAuth
-
- 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;
- }
-
-
- .. ts:def:: BankError
-
- interface BankError {
-
- // Human readable explanation of the failure.
- error: string;
-
- // Numeric Taler error code (`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.
-
- .. ts:def:: BankCancelRequest
-
- 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.
-
-
----------------------
-Querying Transactions
----------------------
-
-
-.. 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 for the bank account of the
- customer specified in the request. Clients must provide authentication
- information via the ``X-Taler-Bank-Username`` and ``Taler-Bank-Password``
- headers.
-
- Transactions are identified by an opaque string identifier, referred to here
- as "row ID". The semantics of the row ID (including its sorting order) are
- determined by the bank server and completely opaque to the client.
-
- The list of returned transactions is determined by a row ID *starting point*
- and a signed non-zero integer *delta*:
-
- * If *delta* is positive, return a list of up to *delta* transactions (all
matching
- the filter criteria) strictly **after** the starting point. The
transactions are sorted
- in **ascending** order of the row ID.
- * If *delta* is negative, return a list of up to *-delta* transactions
(allmatching
- the filter criteria) strictly **before** the starting point. The
transactions are sorted
- in **descending** order of the row ID.
-
- If *starting point* is not explicitly given, it defaults to:
-
- * A value that is **smaller** than all other row IDs if *delta* is
**positive**.
- * A value that is **larger** than all other row IDs if *delta* is
**negative**.
-
- **Request**
-
- :query start: *Optional.*
- Row identifier to explicitly set the *starting point* of the query.
- :query delta:
- The *delta* value that determines the range of the query.
- :query direction:
- Filter transactions by type. Can be ``debit`` to return only
- transactions that debit this account, ``credit`` to return only
transactions
- that credit this account, or ``both`` for both types.
- :query cancelled:
- Filter transactions by their cancellation state.
- Can be ``omit`` to omit rejected transactions or ``show`` to keep rejected
transaction.
- :query account_number:
- Bank account whose history is to be returned.
- *Currently ignored*, as multiple bank accounts per user are not implemented
- yet.
- :query long_poll_ms: *Optional.* If this parameter is specified and the
- result of the query would be empty, the bank will wait up to
``long_poll_ms``
- milliseconds for new transactions that match the query to arrive and only
- then send the HTTP response. A client must never rely on this behavior, as
- the bank may return a response immediately or after waiting only a fraction
- of ``long_poll_ms``.
-
- **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.
-
- .. ts:def:: BankTransaction
-
- 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
-------------------------
-
-.. warning::
-
- This section is completely outdated.
-
-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.
-
-.. ts:def:: WireDetails
-
- interface WireDetails {
- // Only 'test' value admitted so far.
- type: string;
-
- // URL of the bank.
- bank_uri: string;
-
- // bank account number of the user attempting to withdraw.
- account_number: number;
- }
-
-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.
diff --git a/core/api-wire-plugin-bank.rst b/core/api-wire-plugin-bank.rst
new file mode 100644
index 0000000..a56027d
--- /dev/null
+++ b/core/api-wire-plugin-bank.rst
@@ -0,0 +1,171 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2019 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 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/>
+
+==========================
+Taler Bank Wire Plugin API
+==========================
+
+This section describes the API that the ``taler-bank`` wire plugin expects.
+This API is currently implemented by the Taler Demo Bank, as well as by
+LibEuFin (work in progress).
+
+
+--------------
+Authentication
+--------------
+
+The wire plugin authenticates requests to the bank service via the
+``X-Taler-Bank-Username`` and ``X-Taler-Bank-Password`` headers.
+
+-------------------
+Making Transactions
+-------------------
+
+
+.. http:post:: /taler/transaction
+
+ This API allows the exchange to make a transaction, typically to a merchant.
The bank account
+ of the exchange is not included in the request, but instead derived from the
user name in the
+ authentication header.
+
+ To make the API idempotent, the client must include a nonce. Requests with
the same nonce
+ are rejected unless the request is the same.
+
+ **Request:** The body of this request must have the format of a
`TransactionRequest`.
+
+ **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 `TransactionResponse`
+ :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:**
+
+ .. ts:def:: TransactionResponse
+
+ interface TransactionResponse {
+
+ // Timestamp related to the transaction being made.
+ timestamp: Timestamp;
+
+ // Opaque of the transaction that the bank has made.
+ row_id: string;
+ }
+
+ .. ts:def:: TransactionRequest
+
+ interface TransactionResponse {
+ // Nonce to make the request idempotent. Requests with the same
+ // transaction_uid that differ in any of the other fields
+ // are rejected.
+ transaction_uid: HashCode;
+
+ // Amount to transfer.
+ amount: Amount;
+
+ // Reserve public key, will be included in the details
+ // of the wire transfer.
+ reserve_pub: string;
+
+ // The recipient's account identifier as a payto URI
+ credit_account: string;
+ }
+
+
+ .. ts:def:: BankError
+
+ interface BankError {
+
+ // Human readable explanation of the failure.
+ error: string;
+
+ // Numeric Taler error code (`TALER_ErrorCode`)
+ ec: number;
+ }
+
+
+--------------------------------
+Querying the transaction history
+--------------------------------
+
+.. http:get:: /taler/history
+
+ Return a list of transactions made to the exchange. The transaction
+ list shall be filtered to only include transactions that include a valid
+ reserve public key.
+
+ The bank account of the exchange is determined via the user name in the
``X-Taler-Bank-Username`` header.
+ In fact the transaction history might come from a "virtual" account, where
multiple real bank accounts
+ are merged into one history.
+
+ Transactions are identified by an opaque string identifier, referred to here
+ as "row ID". The semantics of the row ID (including its sorting order) are
+ determined by the bank server and completely opaque to the client.
+
+ The list of returned transactions is determined by a row ID *starting point*
+ and a signed non-zero integer *delta*:
+
+ * If *delta* is positive, return a list of up to *delta* transactions (all
matching
+ the filter criteria) strictly **after** the starting point. The
transactions are sorted
+ in **ascending** order of the row ID.
+ * If *delta* is negative, return a list of up to *-delta* transactions
(allmatching
+ the filter criteria) strictly **before** the starting point. The
transactions are sorted
+ in **descending** order of the row ID.
+
+ If *starting point* is not explicitly given, it defaults to:
+
+ * A value that is **smaller** than all other row IDs if *delta* is
**positive**.
+ * A value that is **larger** than all other row IDs if *delta* is
**negative**.
+
+ **Request**
+
+ :query start: *Optional.*
+ Row identifier to explicitly set the *starting point* of the query.
+ :query delta:
+ The *delta* value that determines the range of the query.
+ :query long_poll_ms: *Optional.* If this parameter is specified and the
+ result of the query would be empty, the bank will wait up to
``long_poll_ms``
+ milliseconds for new transactions that match the query to arrive and only
+ then send the HTTP response. A client must never rely on this behavior, as
+ the bank may return a response immediately or after waiting only a fraction
+ of ``long_poll_ms``.
+
+ **Response**
+
+ :status 200 OK: JSON object whose field ``transactions`` is an array of type
`BankTransaction`.
+ :status 204 No content: in case no records exist for the targeted user.
+
+ .. ts:def:: BankTransaction
+
+ interface BankTransaction {
+
+ // Opaque identifier of the returned record
+ row_id: string;
+
+ // Date of the transaction
+ date: Timestamp;
+
+ // Amount transferred
+ amount: Amount;
+
+ // Payto URI to identify the sender of funds
+ debit_account: string;
+
+ // The reserve public key extracted from the transaction details
+ reserve_pub: string;
+ }
+
diff --git a/core/index.rst b/core/index.rst
index 9e770c7..ce4b451 100644
--- a/core/index.rst
+++ b/core/index.rst
@@ -32,6 +32,7 @@ interfaces between the core components of Taler.
api-common
api-error
api-exchange
+ api-wire-plugin-bank
api-merchant
api-auditor
api-bank
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
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.
--
To stop receiving notification emails like this one, please contact
address@hidden.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-docs] branch master updated: restructure bank docs, update wire plugin HTTP API,
gnunet <=