diff options
Diffstat (limited to 'core/api-bank-integration.rst')
| -rw-r--r-- | core/api-bank-integration.rst | 157 |
1 files changed, 80 insertions, 77 deletions
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst index ac1ba63a..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-2023 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 @@ -29,7 +29,7 @@ to tightly integrate with GNU Taler. .. http:get:: /config Return the protocol version and configuration information about the bank. - This specification corresponds to ``current`` protocol being version **2**. + This specification corresponds to ``current`` protocol being **v2**. **Response:** @@ -47,6 +47,7 @@ to tightly integrate with GNU Taler. // 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; @@ -67,7 +68,7 @@ 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 ``WITHDRAWAL_ID``) to interact with the withdrawal operation. @@ -91,36 +92,63 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr 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 + The operation was not found. **Details:** .. ts:def:: BankWithdrawalOperationStatus - export class BankWithdrawalOperationStatus { + 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 + // @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 withdrawal operation id + // It may contain the withdrawal operation id. confirm_transfer_url?: string; // Wire transfer types supported by the bank. @@ -128,43 +156,54 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr // Reserve public key selected by the exchange, // only non-null if ``status`` is ``selected`` or ``confirmed``. - // @since v1 + // @since **v1** selected_reserve_pub?: EddsaPublicKey; - // Exchange account selected by the wallet + // Exchange account selected by the wallet; // only non-null if ``status`` is ``selected`` or ``confirmed``. - // @since v1 + // @since **v1** selected_exchange_account?: string; - // @deprecated since v1, use ``status`` instead + // @deprecated since **v1**, use ``status`` instead // Indicates whether the withdrawal was aborted. aborted: boolean; - // @deprecated since v1, use ``status`` instead + // @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 + // @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: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 public key that should become the wire transfer + // subject to fund the withdrawal. reserve_pub: EddsaPublicKey; - // Payto address of the exchange selected for the withdrawal. - selected_exchange?: string; + // 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:** @@ -175,11 +214,15 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr :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`` : + * ``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_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:** @@ -199,66 +242,25 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr // 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/confirm - Since protocol vC2EC +.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/abort - Allows a provider to notify the Bank about the payment. This will trigger a payment - attestation at the provider, which eventually confirms the payment and allows the - withdrawal. The API is idempotent, meaning sending a payment - notification for the same ``WITHDRAWAL_ID`` return successfuly but not change anything. + 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. - Attention: A bank shall **never** just accept the payment directly but instead attest - the payment using provider specific attestation logic! + Since protocol **v2**. **Request:** - - .. ts:def:: BankWithdrawalConfirmationRequest - - interface WithdrawalConfirmationRequest { - // The provider specific transaction identifier. - // This identifier is used by the bank to attest the - // payment at the providers backend. - provider_transaction_id: string; - - // An identifier, which identifies the device - // processing the payment for the withdrawal - // triggering the confirmation (e.g. Terminal - // or ATM). This is needed to link the withdrawal - // to a terminal owned by a specific provider. - // This will decide about how the withdrawal - // is attested. The device must be known to - // the exchange and be somehow registered. - terminal_id: number; - - // The amount to withdraw. Fees are to be sent in the - // separate field 'fees' and not included in the amount. - amount: Amount; - - // The fees, the customer payed at the providers facility. - card_fees: Amount; - } - **Response** - - :http:statuscode:`204 No content`: - The payment notification was processed successfully. - :http:statuscode:`404 Not found`: - The withdrawal operation was not found. - :http:statuscode:`409 Conflict`: - The withdrawal operation has been aborted previously and can't be aborted - - -.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/abort - - Aborts ``WITHDRAWAL_ID`` operation. Has no effect on an already aborted - operation. - Since protocol v2. + The request body is empty. **Response:** @@ -267,4 +269,5 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr :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. + The withdrawal operation has been confirmed previously and + can't be aborted. |