diff options
-rw-r--r-- | _exts/typescriptdomain.py | 2 | ||||
-rw-r--r-- | core/api-bank-access.rst | 143 | ||||
-rw-r--r-- | core/api-bank-integration.rst (renamed from core/api-bank.rst) | 23 | ||||
-rw-r--r-- | core/api-common.rst | 8 | ||||
-rw-r--r-- | core/index.rst | 3 | ||||
-rw-r--r-- | libeufin/api-nexus.rst | 2 |
6 files changed, 159 insertions, 22 deletions
diff --git a/_exts/typescriptdomain.py b/_exts/typescriptdomain.py index 73a5adaa..b0780eae 100644 --- 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 new file mode 100644 index 00000000..757a2e3c --- /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 0b7b9718..f63fe776 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 9584f240..a7ebe3a7 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 8c86262b..95037d48 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 diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst index fb02858c..745182cf 100644 --- 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 |