From d736e7e9596aa22eb0006d29fe023e57406d16b0 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Mon, 4 Sep 2023 17:06:53 +0200 Subject: bank API refactor --- core/api-bank-access.rst | 302 ----------------------------------------------- 1 file changed, 302 deletions(-) delete mode 100644 core/api-bank-access.rst (limited to 'core/api-bank-access.rst') diff --git a/core/api-bank-access.rst b/core/api-bank-access.rst deleted file mode 100644 index 25dd6cae..00000000 --- a/core/api-bank-access.rst +++ /dev/null @@ -1,302 +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 Affero 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 Affero General Public License for more details. - - You should have received a copy of the GNU Affero General Public License along with - TALER; see the file COPYING. If not, see - - @author Florian Dold - -===================== -Taler Bank Access API -===================== - -This chapter describes the API that the GNU Taler demonstrator bank offers to access accounts. - -This API differs from the "Bank Integration API" in that it provides advanced API access to accounts, as opposed -to enabling wallets to withdraw with a better user experience ("tight integration"). - - ------------------------- -Accounts and Withdrawals ------------------------- - -.. http:get:: ${BANK_API_BASE_URL}/public-accounts - - Show those accounts whose histories are publicly visible. For example, - accounts from donation receivers. As such, this request is unauthenticated. - - **Response** - - **Details** - - .. ts:def:: PublicAccountsResponse - - interface PublicAccountsResponse { - publicAccounts: PublicAccount[] - } - - .. ts:def:: PublicAccount - - interface PublicAccount { - iban: string; - balance: string; - // The account name _and_ the username of the - // Sandbox customer that owns such a bank account. - account_label: string; - } - -The following endpoints require HTTP "Basic" authentication with the account -name and account password, at least in the GNU Taler demo bank implementation. - - -.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name} - - Request the current balance of an account. (New: ) In case of a public bank - account, no authentication is required. - - **Response** - - **Details** - - .. ts:def:: Balance - - interface Balance { - amount: Amount; - credit_debit_indicator: "credit" | "debit"; - } - - .. ts:def:: BankAccountBalanceResponse - - interface BankAccountBalanceResponse { - // Available balance on the account. - balance: Balance; - - // payto://-URI of the account. (New) - payto_uri: string; - - // Number indicating the max debit allowed for the requesting user. - debit_threshold: 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:statuscode:`403 Forbidden`: - The operation was rejected due to insufficient funds. - -.. 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 wallet, or by the bank - // (with the default exchange) in case the wallet did not provide one - // through the Integration API. - 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. - - :http:statuscode:`200 OK`: The withdrawal operation has been aborted. The response is an empty JSON object. - :http:statuscode:`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. - This call is responsible of wiring the funds to the exchange. - - **Response** - - :http:statuscode:`200 OK`: - The withdrawal operation has been confirmed. The response is an empty JSON object. - :http:statuscode:`409 Conflict`: - The withdrawal has been aborted previously and can't be confirmed. - :http:statuscode:`422 Unprocessable Entity` (New): - The withdraw operation cannot be confirmed because no exchange and reserve public key selection happened before. - ------------- -Transactions ------------- - -.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions - - Retrieve a subset of transactions related to $account_name. Without - query parameters, it returns the last 5 transactions. - - **Request** - - :query long_poll_ms: Optional number to express how many milliseconds the server - should wait for at least one result to be shown. If not given, the server - responds immediately, regardless of the result. - :query page: page number starting from 1. Page 1 has the latest transactions - and 1 is the default value. - :query size: how many transactions per page. It must be at least 1 and defaults to 5. - :query from_ms: Optional. Filters the results to transactions *from* (inclusively) this - timestamp in milliseconds - :query until_ms: Optional. Filters the results to transactions *until* (inclusively) this - timestamp in milliseconds - - **Response** - - .. ts:def:: BankAccountTransactionsResponse - - interface BankAccountTransactionsResponse { - transactions: BankAccountTransactionInfo[]; - } - -.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions/${transaction_id} - - **Response** - - Retrieve the transaction whose identifier is ``transaction_id``, - in the following format: - - .. ts:def:: BankAccountTransactionInfo - - interface BankAccountTransactionInfo { - - creditor_iban: string; - creditor_bic: string; // Optional - creditor_name: string; - - debtor_iban: string; - debtor_bic: string; - debtor_name: string; - - amount: number; - currency: string; - subject: string; - - // Transaction unique ID. Matches - // $transaction_id from the URI. - uid: string; - direction: "DBIT" | "CRDT"; - date: Timestamp; - } - - -.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions - - Create a new transaction where the bank account with the label ``account_name`` is **debited**. - - **Request** - - .. ts:def:: BankAccountTransactionCreate - - interface CreateBankAccountTransactionCreate { - - // Address in the Payto format of the wire transfer receiver. - // It needs at least the 'message' query string parameter. - payto_uri: string; - - // Transaction amount (in the $currency:x.y format), optional. - // However, when not given, its value must occupy the 'amount' - // query string parameter of the 'payto' field. In case it - // is given in both places, the payto_uri's takes the precedence. - amount: string; - } - - **Response** - - :http:statuscode:`200 OK`: - the transaction has been created. - - :http:statuscode:`400 Bad Request`: - the request was invalid or the payto://-URI used unacceptable features. - -.. http:delete:: ${BANK_API_BASE_URL}/accounts/${account_name} - - Delete the bank account (and the customer entry) from the database. - Note, customer usernames and bank accounts have the same value. - ----------------------- -Registration (Testing) ----------------------- - -.. http:post:: ${BANK_API_BASE_URL}/testing/register - - Create a new bank account. This endpoint should be disabled for most deployments, but is useful - for automated testing / integration tests. - - **Request** - - .. ts:def:: BankRegistrationRequest - - interface BankRegistrationRequest { - username: string; - password: string; - // Let the request specify the IBAN. In this current - // version, the IBAN validity is NOT checked by the bank - // backend. When missing, the IBAN is generated by the bank. - iban?: string; - // Name of the person who owns the account being made. - name?: string; - // Indicates whether the account is public or not. Defaults to false - is_public?: boolean; - } - - - **Response** - - :http:statuscode:`200 OK`: Registration was successful. -- cgit v1.2.3