summaryrefslogtreecommitdiff
path: root/core/api-bank-integration.rst
diff options
context:
space:
mode:
Diffstat (limited to 'core/api-bank-integration.rst')
-rw-r--r--core/api-bank-integration.rst153
1 files changed, 105 insertions, 48 deletions
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
index 5ed98be1..4131a28a 100644
--- a/core/api-bank-integration.rst
+++ b/core/api-bank-integration.rst
@@ -1,7 +1,7 @@
..
This file is part of GNU TALER.
- Copyright (C) 2014-2020 Taler Systems SA
+ Copyright (C) 2014-2023 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
@@ -28,31 +28,37 @@ to tightly integrate with GNU Taler.
.. http:get:: /config
- Get configuration information about the bank.
-
- **Request:**
+ Return the protocol version and configuration information about the bank.
+ This specification corresponds to ``current`` protocol being version **2**.
**Response:**
:http:statuscode:`200 OK`:
- The exchange responds with a `BankVersion` object. This request should
+ The exchange responds with a `IntegrationConfig` object. This request should
virtually always be successful.
**Details:**
- .. ts:def:: BankVersion
+ .. ts:def:: IntegrationConfig
+
+ interface IntegrationConfig {
+ // Name of the API.
+ name: "taler-bank-integration";
- 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;
+ // URN of the implementation (needed to interpret 'revision' in version).
+ // @since v2, may become mandatory in the future.
+ implementation?: string;
+
// Currency used by this bank.
currency: string;
- // Name of the API.
- name: "taler-bank-integration";
+ // How the bank SPA should render this currency.
+ currency_specification: CurrencySpecification;
}
@@ -63,41 +69,42 @@ 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.
+for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation.
-.. http:get:: ${BANK_API_BASE_URL}/withdrawal-operation/${wopid}
+.. http:get:: /withdrawal-operation/$WITHDRAWAL_ID
- Query information about a withdrawal operation, identified by the ``wopid``.
+ Query information about a withdrawal operation, identified by the ``WITHDRAWAL_ID``.
- **Request**
+ **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
+ milliseconds for operationt state to be different from ``old_state`` before sending the HTTP
response. A client must never rely on this behavior, as the bank may
return a response immediately.
+ :query old_state:
+ *Optional.* Default to "pending".
- **Response**
+ **Response:**
:http:statuscode:`200 OK`:
The withdrawal operation is known to the bank, and details are given
in the `BankWithdrawalOperationStatus` response body.
+ :http:statuscode:`404 Not found`:
+ The operation was not found
+ **Details:**
.. ts:def:: BankWithdrawalOperationStatus
export class BankWithdrawalOperationStatus {
- // Indicates whether the withdrawal was aborted.
- aborted: boolean;
-
- // 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;
+ // Current status of the operation
+ // pending: the operation is pending parameters selection (exchange and reserve public key)
+ // selected: the operations has been selected and is pending confirmation
+ // aborted: the operation has been aborted
+ // confirmed: the transfer has been confirmed and registered by the bank
+ // Since protocol v1.
+ status: "pending" | "selected" | "aborted" | "confirmed";
// Amount that will be withdrawn with this operation
// (raw amount without fee considerations).
@@ -112,53 +119,103 @@ for the withdrawal operation (the ``wopid``) to interact with the withdrawal ope
// URL that the user needs to navigate to in order to
// complete some final confirmation (e.g. 2FA).
+ // Only applicable when ``status`` is ``selected`` or ``pending``.
+ // It may contain withdrawal operation id
confirm_transfer_url?: string;
// Wire transfer types supported by the bank.
wire_types: string[];
- }
-.. http:post:: ${BANK_API_BASE_URL}/withdrawal-operation/${wopid}
+ // Reserve public key selected by the exchange,
+ // only non-null if ``status`` is ``selected`` or ``confirmed``.
+ // Since protocol v1.
+ selected_reserve_pub?: string;
- **Request** The body of this request must have the format of a `BankWithdrawalOperationPostRequest`.
+ // Exchange account selected by the wallet
+ // only non-null if ``status`` is ``selected`` or ``confirmed``.
+ // Since protocol v1.
+ selected_exchange_account?: string;
- **Response**
+ // Deprecated field since protocol v1 use ``status`` instead
+ // Indicates whether the withdrawal was aborted.
+ aborted: boolean;
- :http:statuscode:`200 OK`:
- The bank has accepted the withdrawal operation parameters chosen by the wallet.
- The response is a `BankWithdrawalOperationPostResponse`.
- :http:statuscode:`404 Not found`:
- The bank does not know about a withdrawal operation with the specified ``wopid``.
- :http:statuscode:`409 Conflict` (New):
- The wallet selected a different exchange or reserve public key under the same withdrawal ID.
+ // Deprecated field since protocol v1 use ``status`` instead
+ // Has the wallet selected parameters for the withdrawal operation
+ // (exchange and reserve public key) and successfully sent it
+ // to the bank?
+ selection_done: boolean;
+
+ // Deprecated field since protocol v1 use ``status`` instead
+ // 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;
+ }
- **Details**
+.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
+
+ **Request:**
.. 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.
+ // Payto address of the exchange selected for the withdrawal.
selected_exchange: string;
}
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The bank has accepted the withdrawal operation parameters chosen by the wallet.
+ The response is a `BankWithdrawalOperationPostResponse`.
+ :http:statuscode:`404 Not found`:
+ The bank does not know about a withdrawal operation with the specified ``WITHDRAWAL_ID``.
+ :http:statuscode:`409 Conflict`:
+ * ``TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT`` :
+ The wallet selected a different exchange or reserve public key under the same withdrawal ID.
+ * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT`` : the reserve public key is already used.
+ * ``TALER_EC_BANK_UNKNOWN_ACCOUNT`` : the selected exchange account was not found.
+ * ``TALER_EC_BANK_ACCOUNT_IS_NOT_EXCHANGE`` : the selected account is not an exchange.
+
+ **Details:**
+
.. 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;
+ // Current status of the operation
+ // pending: the operation is pending parameters selection (exchange and reserve public key)
+ // selected: the operations has been selected and is pending confirmation
+ // aborted: the operation has been aborted
+ // confirmed: the transfer has been confirmed and registered by the bank
+ status: "selected" | "aborted" | "confirmed";
// 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``.
+ // Only applicable when ``status`` is ``selected`` or ``pending``.
+ // It may contain withdrawal operation id
confirm_transfer_url?: string;
+
+ // Deprecated field use ``status`` instead
+ // 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;
}
+
+.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/abort
+
+ Aborts ``WITHDRAWAL_ID`` operation. Has no effect on an already aborted
+ operation.
+ Since protocol v2.
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ The withdrawal operation has been aborted.
+ :http:statuscode:`404 Not found`:
+ The withdrawal operation was not found.
+ :http:statuscode:`409 Conflict`:
+ The withdrawal operation has been confirmed previously and can't be aborted.