summaryrefslogtreecommitdiff
path: root/core/api-bank-access.rst
diff options
context:
space:
mode:
Diffstat (limited to 'core/api-bank-access.rst')
-rw-r--r--core/api-bank-access.rst272
1 files changed, 0 insertions, 272 deletions
diff --git a/core/api-bank-access.rst b/core/api-bank-access.rst
deleted file mode 100644
index a33cbdbb..00000000
--- a/core/api-bank-access.rst
+++ /dev/null
@@ -1,272 +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 <http://www.gnu.org/licenses/>
-
- @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.
- accountLabel: 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:: BankAccountBalanceResponse
-
- interface BankAccountBalanceResponse {
- // Available balance on the account.
- balance: {
- amount: Amount;
- credit_debit_indicator: "credit" | "debit";
- };
- // payto://-URI of the account. (New)
- paytoUri: 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 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 page: page number (defaults to 1, meaning the page with the latest transactions.)
- :query size: how many transactions per page, defaults to 5.
-
- **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 {
-
- creditorIban: string;
- creditorBic: string; // Optional
- creditorName: string;
-
- debtorIban: string;
- debtorBic: string;
- debtorName: string;
-
- amount: number;
- currency: string;
- subject: string;
-
- // Transaction unique ID. Matches
- // $transaction_id from the URI.
- uid: string;
- direction: "DBIT" | "CRDT";
- date: string; // YYYY-MM-DD ending with 'Z'
- }
-
-
-.. 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.
- paytoUri: 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 paytoUri'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.
-
-----------------------
-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;
- }
-
-
- **Response**
-
- :http:statuscode:`200 OK`: Registration was successful.