From 0e650e78865fef95adc61021dabce4f294c83ad4 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Mon, 17 Feb 2020 20:34:20 +0100 Subject: bank API split, bank access API docs --- core/api-bank-access.rst | 143 ++++++++++++++++++++++++++++++++++ core/api-bank-integration.rst | 158 ++++++++++++++++++++++++++++++++++++++ core/api-bank.rst | 175 ------------------------------------------ core/api-common.rst | 8 ++ core/index.rst | 3 +- 5 files changed, 311 insertions(+), 176 deletions(-) create mode 100644 core/api-bank-access.rst create mode 100644 core/api-bank-integration.rst delete mode 100644 core/api-bank.rst (limited to 'core') 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 + + @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 new file mode 100644 index 00000000..f63fe776 --- /dev/null +++ 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 + + @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 deleted file mode 100644 index 0b7b9718..00000000 --- a/core/api-bank.rst +++ /dev/null @@ -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 - - @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 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 -- cgit v1.2.3