commit 0e650e78865fef95adc61021dabce4f294c83ad4
parent 30f02dcb7137d84d1e9d901e20e990af84b5ec2c
Author: Florian Dold <florian.dold@gmail.com>
Date: Mon, 17 Feb 2020 20:34:20 +0100
bank API split, bank access API docs
Diffstat:
7 files changed, 314 insertions(+), 177 deletions(-)
diff --git a/_exts/typescriptdomain.py b/_exts/typescriptdomain.py
@@ -388,7 +388,7 @@ class LinkingHtmlFormatter(HtmlFormatter):
if tok_getprop(tok, "is_identifier"):
if xref.startswith('"'):
return value
- if xref in ("number", "object", "string", "boolean", "any", "true", "false"):
+ if xref in ("number", "object", "string", "boolean", "any", "true", "false", "null"):
return value
if xref is None:
diff --git a/core/api-bank-access.rst b/core/api-bank-access.rst
@@ -0,0 +1,143 @@
+..
+ This file is part of GNU TALER.
+
+ Copyright (C) 2014-2020 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 Florian Dold
+
+=============================
+Taler Bank Account Access API
+=============================
+
+This chapter describes the API that the GNU Taler demonstrator bank offers to access accounts.
+
+This API differes from the "Bank Integration API" in that it provides advanced API access to accounts, as opposed
+to enabling wallets to withdraw with an better user experience ("tight integration").
+
+
+.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/balance
+
+ Request the current balance of an account.
+
+ **Response**
+
+ **Details**
+
+ .. ts:def:: BankAccountBalanceResponse
+
+ interface BankAccountBalanceResponse {
+ // Amount with plus or minus sign, representing the current
+ // available account balance.
+ balance: SignedAmount;
+ }
+
+
+.. http:POST:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals
+
+ Create a withdrawal operation, resulting in a ``taler://withdraw`` URI.
+
+ **Response**
+
+ **Details**
+
+ .. ts:def:: BankAccountCreateWithdrawalResponse
+
+ interface BankAccountCreateWithdrawalResponse {
+ // ID of the withdrawal, can be used to view/modify the withdrawal operation
+ withdrawal_id: string;
+
+ // URI that can be passed to the wallet to initiate the withdrawal
+ taler_withdraw_uri: string;
+ }
+
+
+.. http:POST:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals
+
+ Create a withdrawal operation, resulting in a ``taler://withdraw`` URI.
+
+ **Request**
+
+ .. ts:def:: BankAccountCreateWithdrawalRequest
+
+ interface BankAccountCreateWithdrawalRequest {
+ // Amount to withdraw
+ amount: Amount;
+ }
+
+ **Response**
+
+ .. ts:def:: BankAccountCreateWithdrawalResponse
+
+ interface BankAccountCreateWithdrawalResponse {
+ // ID of the withdrawal, can be used to view/modify the withdrawal operation
+ withdrawal_id: string;
+
+ // URI that can be passed to the wallet to initiate the withdrawal
+ taler_withdraw_uri: string;
+ }
+
+
+.. http:GET:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}
+
+ Query the status of a withdrawal operation
+
+ **Response**
+
+ **Details**
+
+ .. ts:def:: BankAccountGetWithdrawalResponse
+
+ interface BankAccountGetWithdrawalResponse {
+ // Amount that will be withdrawn with this withdrawal operation
+ amount: Amount;
+
+ // Was the withdrawal aborted?
+ aborted: boolean;
+
+ // Has the withdrawal been confirmed by the bank?
+ // The wire transfer for a withdrawal is only executed once
+ // both confirmation_done is true and selection_done is true.
+ confirmation_done: boolean;
+
+ // Did the wallet select reserve details?
+ selection_done: boolean;
+
+ // Reserve public key selected by the exchange,
+ // only non-null if selection_done is 'true'
+ selected_reserve_pub: string | null;
+
+ // Exchange account selected by the exchange,
+ // only non-null if selection_done is 'true'
+ selected_exchange_account: string | null;
+ }
+
+
+.. http:POST:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/abort
+
+ Abort a withdrawal operation. Has no effect on an already aborted withdrawal operation.
+
+ :status 200 OK: The withdrawl operation has been aborted. The response is an empty JSON object.
+ :status 409 Conflict: The reserve operation has been confirmed previously and can't be aborted.
+
+
+.. http:POST:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/confirm
+
+ Confirm a withdrawal operation. Has no effect on an already confirmed withdrawal operation.
+
+ **Response**
+
+ :status 200 OK: The withdrawl operation has been confirmed. The response is an empty JSON object.
+ :status 409 Conflict: The reserve operation has been aborted previously and can't be confirmed.
+
+
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
@@ -0,0 +1,158 @@
+..
+ This file is part of GNU TALER.
+
+ Copyright (C) 2014-2020 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
+
+==========================
+Taler Bank Integration API
+==========================
+
+This chapter describe the APIs that banks need to offer towards Taler wallets
+to tightly integrate with GNU Taler.
+
+.. contents:: Table of Contents
+
+.. http:get:: /config
+
+ Get a configuration information about the bank.
+
+ **Request:**
+
+ **Response:**
+
+ :status 200 OK:
+ The exchange responds with a `BankVersion` object. This request should
+ virtually always be successful.
+
+ **Details:**
+
+ .. ts:def:: BankVersion
+
+ interface BankVersion {
+ // libtool-style representation of the Bank protocol version, see
+ // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
+ // The format is "current:revision:age".
+ version: string;
+
+ // currency used by this bank
+ currency: string;
+
+ }
+
+
+-----------
+Withdrawing
+-----------
+
+Withdrawals with a Taler-integrated bank are based on withdrawal operations.
+Some user interaction (on the Bank's website or a Taler-enabled ATM) creates a
+withdrawal operation record in the Bank's database. The wallet can use a unique identifier
+for the withdrawal operation (the ``wopid``) to interact with the withdrawal operation.
+
+.. http:get:: ${BANK_API_BASE_URL}/withdrawal-operation/${wopid}
+
+ Query information about a withdrawal operation, identified by the ``wopid``.
+
+ **Request**
+
+ :query long_poll_ms:
+ *Optional.* If specified, the bank will wait up to ``long_poll_ms``
+ milliseconds for completion of the transfer before sending the HTTP
+ response. A client must never rely on this behavior, as the bank may
+ return a response immediately.
+
+ **Response**
+
+ :status 200 OK:
+ The withdrawal operation is known to the bank, and details are given
+ in the `BankWithdrawalOperationStatus` response body.
+
+
+ .. ts:def:: BankWithdrawalOperationStatus
+
+ export class BankWithdrawalOperationStatus {
+ // has the wallet selected parameters for the withdrawal operation
+ // (exchange and reserve public key) and successfully sent it
+ // to the bank?
+ selection_done: boolean;
+
+ // The transfer has been confirmed and registered by the bank.
+ // Does not guarantee that the funds have arrived at the exchange already.
+ transfer_done: boolean;
+
+ // Amount that will be withdrawn with this operation
+ // (raw amount without fee considerations).
+ amount: Amount;
+
+ // Bank account of the customer that is withdrawing, as a
+ // payto URI.
+ sender_wire?: string;
+
+ // Suggestion for an exchange given by the bank.
+ suggested_exchange?: string;
+
+ // URL that the user needs to navigate to in order to
+ // complete some final confirmation (e.g. 2FA).
+ confirm_transfer_url?: string;
+
+ // Wire transfer types supported by the bank.
+ wire_types: string[];
+ }
+
+.. http:post:: ${BANK_API_BASE_URL}/withdrawal-operation/${wopid}
+
+ **Request** The body of this request must have the format of a `BankWithdrawalOperationPostRequest`.
+
+ **Response**
+
+ :status 200 OK:
+ The bank has accepted the withdrawal operation parameters chosen by the wallet.
+ The response is a `BankWithdrawalOperationPostResponse`.
+ :status 404 Not Found:
+ The bank does not know about a withdrawal operation with the specified ``wopid``.
+
+ **Details**
+
+ .. ts:def:: BankWithdrawalOperationPostRequest
+
+ interface BankWithdrawalOperationPostRequest {
+
+ // 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;
+ }
+
+ .. ts:def:: BankWithdrawalOperationPostResponse
+
+ interface BankWithdrawalOperationPostResponse {
+
+ // The transfer has been confirmed and registered by the bank.
+ // Does not guarantee that the funds have arrived at the exchange already.
+ transfer_done: boolean;
+
+ // URL that the user needs to navigate to in order to
+ // complete some final confirmation (e.g. 2FA).
+ //
+ // Only applicable when 'transfer_done' is false.
+ confirm_transfer_url?: string;
+ }
+
diff --git a/core/api-bank.rst b/core/api-bank.rst
@@ -1,175 +0,0 @@
-..
- This file is part of GNU TALER.
-
- Copyright (C) 2014-2020 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
-
-==============
-Taler Bank API
-==============
-
-This chapter describe the APIs that banks need to offer towards Taler wallets
-to tightly integrate with GNU Taler.
-
-.. contents:: Table of Contents
-
-.. http:get:: /config
-
- Get a configuration information about the bank.
-
- **Request:**
-
- **Response:**
-
- :status 200 OK:
- The exchange responds with a `BankVersion` object. This request should
- virtually always be successful.
-
- **Details:**
-
- .. ts:def:: BankVersion
-
- interface BankVersion {
- // libtool-style representation of the Bank protocol version, see
- // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
- // The format is "current:revision:age".
- version: string;
-
- // currency used by this bank
- currency: string;
-
- }
-
-
------------
-Withdrawing
------------
-
-Withdrawals with a Taler-integrated bank are based on withdrawal operations.
-Some user interaction (on the Bank's website or a Taler-enabled ATM) creates a
-withdrawal operation record in the Bank's database. The wallet can use a unique identifier
-for the withdrawal operation (the ``wopid``) to interact with the withdrawal operation.
-
-.. http:get:: ${BANK_API_BASE_URL}/withdrawal-operation/${wopid}
-
- Query information about a withdrawal operation, identified by the ``wopid``.
-
- **Request**
-
- :query long_poll_ms:
- *Optional.* If specified, the bank will wait up to ``long_poll_ms``
- milliseconds for completion of the transfer before sending the HTTP
- response. A client must never rely on this behavior, as the bank may
- return a response immediately.
-
- **Response**
-
- :status 200 OK:
- The withdrawal operation is known to the bank, and details are given
- in the `BankWithdrawalOperationStatus` response body.
-
-
- .. ts:def:: BankWithdrawalOperationStatus
-
- export class BankWithdrawalOperationStatus {
- // has the wallet selected parameters for the withdrawal operation
- // (exchange and reserve public key) and successfully sent it
- // to the bank?
- selection_done: boolean;
-
- // The transfer has been confirmed and registered by the bank.
- // Does not guarantee that the funds have arrived at the exchange already.
- transfer_done: boolean;
-
- // Amount that will be withdrawn with this operation
- // (raw amount without fee considerations).
- amount: Amount;
-
- // Bank account of the customer that is withdrawing, as a
- // payto URI.
- sender_wire?: string;
-
- // Suggestion for an exchange given by the bank.
- suggested_exchange?: string;
-
- // URL that the user needs to navigate to in order to
- // complete some final confirmation (e.g. 2FA).
- confirm_transfer_url?: string;
-
- // Wire transfer types supported by the bank.
- wire_types: string[];
- }
-
-.. http:post:: ${BANK_API_BASE_URL}/withdrawal-operation/${wopid}
-
- **Request** The body of this request must have the format of a `BankWithdrawalOperationPostRequest`.
-
- **Response**
-
- :status 200 OK:
- The bank has accepted the withdrawal operation parameters chosen by the wallet.
- The response is a `BankWithdrawalOperationPostResponse`.
- :status 404 Not Found:
- The bank does not know about a withdrawal operation with the specified ``wopid``.
-
- **Details**
-
- .. ts:def:: BankWithdrawalOperationPostRequest
-
- interface BankWithdrawalOperationPostRequest {
-
- // 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;
- }
-
- .. ts:def:: BankWithdrawalOperationPostResponse
-
- interface BankWithdrawalOperationPostResponse {
-
- // The transfer has been confirmed and registered by the bank.
- // Does not guarantee that the funds have arrived at the exchange already.
- transfer_done: boolean;
-
- // URL that the user needs to navigate to in order to
- // complete some final confirmation (e.g. 2FA).
- //
- // Only applicable when 'transfer_done' is false.
- confirm_transfer_url?: string;
- }
-
-
-------------
-Testing APIs
-------------
-
-The following APIs are exposed by some bank API implementations **for testing** as part
-of the wallet's integration tests.
-
-.. warning::
-
- These APIs **must not** be offered by any production systems.
-
-.. http:post:: ${BANK_API_BASE_URL}/testing/register
-
-.. http:post:: ${BANK_API_BASE_URL}/testing/withdraw
-
-.. http:post:: ${BANK_API_BASE_URL}/testing/withdraw-uri
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -335,6 +335,14 @@ Internally, amounts are parsed into the following object:
}
+An amount that is prefixed with a ``+`` or ``-`` character is also used in certain contexts.
+When no sign is present, the amount is assumed to be positive.
+
+.. ts:def:: SignedAmount
+
+ type SignedAmount = string;
+
+
--------------
Binary Formats
--------------
diff --git a/core/index.rst b/core/index.rst
@@ -35,7 +35,8 @@ interfaces between the core components of Taler.
api-wire
api-merchant
api-auditor
- api-bank
+ api-bank-integration
+ api-bank-access
wireformats
api-sync
taler-uri
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
@@ -69,6 +69,7 @@ Low-level EBICS API
.. ts:def:: NexusEbicsBackupResponse
+
interface NexusEbicsBackupResponse {
// The three passphrase-protected private keys in the PKCS#8 format
@@ -89,6 +90,7 @@ Low-level EBICS API
"{id}" account, and fails if it exists already.
.. ts:def:: NexusEbicsRestoreBackupRequest
+
interface NexusEbicsRestoreBackupRequest {
// passphrase to decrypt the keys
