diff options
Diffstat (limited to 'core/api-bank-integration.rst')
| -rw-r--r-- | core/api-bank-integration.rst | 223 |
1 files changed, 166 insertions, 57 deletions
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst index 5ed98be1..e7db1efc 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-2024 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,38 @@ 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 **v2**. **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; } @@ -61,104 +68,206 @@ 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 +Some user interaction (on the bank's websitei) 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; + interface BankWithdrawalOperationStatus { + // 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 **v1** + status: "pending" | "selected" | "aborted" | "confirmed"; // 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. + // (raw amount without fee considerations). Only + // given once the amount is fixed and cannot be changed. + // Optional since **vC2EC**. + amount?: Amount; + + // Suggestion for the amount to be withdrawn with this + // operation. Given if a suggestion was made but the + // user may still change the amount. + // Optional since **vC2EC**. + suggested_amount?: Amount; + + // Maximum amount that the wallet can choose to withdraw. + // Only applicable when the amount is not fixed. + // @since **vC2EC**. + max_amount?: Amount; + + // The non-Taler card fees the customer will have + // to pay to the bank / payment service provider + // they are using to make the withdrawal. + // @since **vC2EC** + card_fees?: Amount; + + // Bank account of the customer that is debiting, as an + // RFC 8905 ``payto`` URI. sender_wire?: string; - // Suggestion for an exchange given by the bank. + // Base URL of the suggested exchange. The bank may have + // neither a suggestion nor a requirement for the exchange. + // This value is typically set in the bank's configuration. suggested_exchange?: string; + // Base URL of an exchange that must be used. Optional, + // not given *unless* a particular exchange is mandatory. + // This value is typically set in the bank's configuration. + // @since **vC2EC** + required_exchange?: string; + // 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 the 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 **v1** + selected_reserve_pub?: EddsaPublicKey; - **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 **v1** + selected_exchange_account?: string; + + // @deprecated since **v1**, use ``status`` instead + // Indicates whether the withdrawal was aborted. + aborted: boolean; - **Response** + // @deprecated since **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 since **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; + } - :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. - **Details** +.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID + + This endpoint is used by the GNU Taler wallet to supply additional + details needed to complete a withdraw operation. + + **Request:** .. ts:def:: BankWithdrawalOperationPostRequest interface BankWithdrawalOperationPostRequest { - // Reserve public key. - reserve_pub: string; + // Reserve public key that should become the wire transfer + // subject to fund the withdrawal. + reserve_pub: EddsaPublicKey; - // 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. + // RFC 8905 (payto) address of the exchange account to be + // credited for the withdrawal. selected_exchange: string; + + // Selected amount to be transferred. Optional if the + // backend already knows the amount. + // @since **vC2EC** + amount?: Amount; } + **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. + * ``TALER_EC_BANK_AMOUNT_DIFFERS`` : the specified amount will not work for this + withdrawal (since **vC2EC**). + * ``TALER_EC_BANK_AMOUNT_REQUIRED`` : the backend requires an amount to be + specified (since **vC2EC**). + + **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; + + // 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. This endpoint can be used by the wallet if the user aborts + the transaction, ensuring that the operation is also aborted at the + bank. + + Since protocol **v2**. + + **Request:** + + The request body is empty. + + **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. |