diff options
Diffstat (limited to 'core/api-bank-access.rst')
| -rw-r--r-- | core/api-bank-access.rst | 141 |
1 files changed, 130 insertions, 11 deletions
diff --git a/core/api-bank-access.rst b/core/api-bank-access.rst index ddb2ec80..8ac135cd 100644 --- a/core/api-bank-access.rst +++ b/core/api-bank-access.rst @@ -30,13 +30,39 @@ to enabling wallets to withdraw with a better user experience ("tight integratio 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. + Request the current balance of an account. (New: ) In case of a public bank + account, no authentication is required. **Response** @@ -50,10 +76,12 @@ name and account password, at least in the GNU Taler demo bank implementation. 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 +.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals Create a withdrawal operation, resulting in a ``taler://withdraw`` URI. @@ -78,8 +106,10 @@ name and account password, at least in the GNU Taler demo bank implementation. 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} +.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id} Query the status of a withdrawal operation. @@ -108,13 +138,14 @@ name and account password, at least in the GNU Taler demo bank implementation. // 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``. + // 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 +.. 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. @@ -122,24 +153,112 @@ name and account password, at least in the GNU Taler demo bank implementation. :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 +.. 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 reserve operation has been aborted previously and can't be confirmed. + :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. + +.. 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 +.. 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. |