summaryrefslogtreecommitdiff
path: root/core
diff options
context:
space:
mode:
Diffstat (limited to 'core')
-rw-r--r--core/api-bank-access.rst143
-rw-r--r--core/api-bank-integration.rst (renamed from core/api-bank.rst)23
-rw-r--r--core/api-common.rst8
-rw-r--r--core/index.rst3
4 files changed, 156 insertions, 21 deletions
diff --git a/core/api-bank-access.rst b/core/api-bank-access.rst
new file mode 100644
index 0000000..757a2e3
--- /dev/null
+++ 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.rst b/core/api-bank-integration.rst
index 0b7b971..f63fe77 100644
--- a/core/api-bank.rst
+++ b/core/api-bank-integration.rst
@@ -17,9 +17,9 @@
@author Marcello Stanisci
@author Christian Grothoff
-==============
-Taler Bank API
-==============
+==========================
+Taler Bank Integration API
+==========================
This chapter describe the APIs that banks need to offer towards Taler wallets
to tightly integrate with GNU Taler.
@@ -156,20 +156,3 @@ for the withdrawal operation (the ``wopid``) to interact with the withdrawal ope
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
index 9584f24..a7ebe3a 100644
--- 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
index 8c86262..95037d4 100644
--- 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