diff options
Diffstat (limited to 'taler-wallet.rst')
| -rw-r--r-- | taler-wallet.rst | 1198 |
1 files changed, 245 insertions, 953 deletions
diff --git a/taler-wallet.rst b/taler-wallet.rst index 0d889a3a..4a975340 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -1,65 +1,28 @@ -GNU Taler Wallet Developer Manual -################################# +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 Taler Systems SA -The GNU Taler wallet allows customers to withdraw and spend digital cash. - -.. _command-line-wallet: - -Command-line Wallet -=================== - -The command-line wallet is used primarily for testing by developers. - -Building from source --------------------- - -.. code-block:: console - - $ git clone https://git.taler.net/wallet-core.git - $ cd wallet-core - $ ./bootstrap - $ ./configure --prefix=$INSTALL_PREFIX - $ make && make install - -The wallet command-line interface should then be available as ``taler-wallet-cli`` under ``$INSTALL_PREFIX/bin``. - -Installation via NPM --------------------- + 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. -The wallet can also obtained via NPM, the Node Package Manager. - -To install the wallet as a global package, run: + 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. -.. code-block:: console - - $ npm install -g taler-wallet - # check if installation was successful - $ taler-wallet-cli --version + 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/> -To install the wallet only for your user, run: -.. code-block:: console +Wallet Manual +############# - $ npm install -g --prefix=$HOME/local taler-wallet - # check if installation was successful - $ taler-wallet-cli --version - # If this fails, make sure that $HOME/local/bin is in your $PATH - -To use the wallet as a library in your own project, run: - -.. code-block:: console - - $ npm install taler-wallet - - -Manual withdrawing -================== +The GNU Taler wallet allows customers to withdraw and spend digital cash. -.. code-block:: console +.. contents:: Table of Contents + :depth: 1 + :local: - $ taler-wallet-cli advanced withdraw-manually \ - --exchange https://exchange.eurint.taler.net/ \ - --amount EUR:5 WebExtension Wallet =================== @@ -83,556 +46,344 @@ Android Wallet Please see :ref:`Build-apps-from-source` in the :doc:`taler-developer-manual`. -APIs and Data Formats -===================== +iOS Wallet +========== -.. warning:: +Please see :ref:`Build-iOS-from-source` in the :doc:`taler-developer-manual`. - These APIs are still a work in progress and *not* final. +.. _command-line-wallet: -Envelope Format ---------------- +Command-line Wallet +=================== -All API responses and notifications are returned in the -following envelope: +This section describes how to use the GNU Taler wallet command line +interface (CLI). -.. ts:def:: WalletResponseEnvelope +The the wallet CLI is targeted at developers and operators, but not meant to be +used by customers. It exposes all functionality that the more user-friendly +interfaces (Android app, browser extension) offer. However, it provides more +diagnostics and advanced features as well. - type WalletResponseEnvelope = - | WalletSuccess - | WalletError - | WalletNotification +Building from source +-------------------- -.. ts:def:: WalletSuccess +The easiest way to install the wallet is via NPM. Note that a recent version of +Node.JS (``>=12.20.1``) is required. - export interface WalletSuccess { - type: "response"; - operation: string, - // ID to correlate success response to request - id: string; - // Result type depends on operation - result: unknown; - } +We recommend to install the wallet package on a per-user basis, +thus setting ``$INSTALL_PREFIX`` to a directory in ``$HOME``. -.. ts:def:: WalletError +.. code-block:: console - export interface WalletError { - type: "error"; - operation: string, - // ID to correlate error response to request - id: string; - error: WalletErrorInfo; - } + $ git clone https://git.taler.net/wallet-core.git + $ cd wallet-core + $ ./bootstrap + $ ./configure --prefix=$INSTALL_PREFIX + $ make && make install -.. ts:def:: WalletNotification +The wallet command-line interface should then be available as ``taler-wallet-cli`` under ``$INSTALL_PREFIX/bin``. - export interface WalletSuccess { - type: "notification"; +Installation via NPM +-------------------- - // actual type is WalletNotification, - // to be documented here - payload: any; - } +The wallet can also obtained via NPM, the Node Package Manager. -.. ts:def:: WalletErrorInfo +To install the wallet as a global package, run: - export interface WalletErrorInfo { - // Numeric error code defined defined in the - // GANA gnu-taler-error-codes registry. - talerErrorCode: number; +.. code-block:: console - // English description of the error code. - talerErrorHint: string; + $ npm install -g taler-wallet + # check if installation was successful + $ taler-wallet-cli --version - // English diagnostic message that can give details - // for the instance of the error. - message: string; +To install the wallet only for your user, run: - // Error details, type depends - // on talerErrorCode - details: unknown; - } +.. code-block:: console -Balances --------- + $ npm install -g --prefix=$HOME/local taler-wallet + # check if installation was successful + $ taler-wallet-cli --version + # If this fails, make sure that $HOME/local/bin is in your $PATH -Balances are the amounts of digital cash held by the wallet. +To use the wallet as a library in your own project, run: -:name: ``"getBalances"`` -:description: Get a list of balances per currency. -:response: - .. ts:def:: BalancesResponse +.. code-block:: console - interface BalancesResponse { - // a list of balances sorted by currency. - // (currencies with shorter names first, then lexically ascending). - // - // Note: Even when a currency has no balance, but pending or past transactions, - // it should be included in this list with a balance of zero. - balances: Balance[]; - } + $ npm install taler-wallet - .. ts:def:: Balance - - // Balance for one currency. - // The currency can be derived from any of the - // "Amount" fields, as the currency is present even - // when the amount is zero. - interface Balance { - // The total Amount that is currently available to be spent - // including amounts tied up in ongoing refresh operations. These are hidden from the user. - // If the user tries to spend coins locked up this way, - // the wallet will give an error message different from "insufficient balance". - available: Amount; - - // the total incoming amount that will be added to the available balance - // when all pending transactions succeed (including internal refreshes) - pendingIncoming: Amount; - - // the total outgoing amount that will be subtracted from the available balance - // when all pending transactions succeed (including internal refreshes) - pendingOutgoing: Amount; - - // true if the balance requires user-interaction, e.g. accepting a tip - // (DEV: can be left out of a first implementation) - requiresUserInput: boolean; - } -Transactions +Getting Help ------------ -Transactions are all operations or events that affect the balance. - -:Name: ``"getTransactions"`` -:Description: Get a list of past and pending transactions. -:Request: - .. ts:def:: TransactionsRequest - - interface TransactionsRequest { - // return only transactions in the given currency, if present - currency?: string; - - // if present, results will be limited to transactions related to the given search string - search?: string; - } -:Response: - .. ts:def:: TransactionsResponse - - interface TransactionsResponse { - // a list of past and pending transactions sorted by pending, timestamp and transactionId. - // In case two events are both pending and have the same timestamp, - // they are sorted by the transactionId - // (i.e. pending before non-pending transactions, newer before older - // and if all equal transactionId lexically ascending). - transactions: Transaction[]; - } - - .. ts:def:: Transaction - - interface Transaction { - // opaque unique ID for the transaction, used as a starting point for paginating queries - // and for invoking actions on the transaction (e.g. deleting/hiding it from the history) - transactionId: string; - - // the type of the transaction; different types might provide additional information - type: TransactionType; - - // main timestamp of the transaction - timestamp: Timestamp; +The wallet CLI comes with built-in help. Invoke the wallet CLI (or any subcommand) with the ``--help`` flag to get help: - // true if the transaction is still pending, false otherwise - // If a transaction is not longer pending, its timestamp will be updated, - // but its transactionId will remain unchanged - pending: boolean; - - // if present, the transaction encountered a fatal error that needs to be shown to the user - error?: TransactionError; - - // Raw amount of the transaction (exclusive of fees or other extra costs) - amountRaw: Amount; - - // Amount added or removed from the wallet's balance (including all fees and other costs) - amountEffective: Amount; - } - - .. ts:def:: TransactionType - - type TransactionType = ( - TransactionWithdrawal | - TransactionPayment | - TransactionRefund | - TransactionTip | - TransactionRefresh - ) - - .. ts:def:: TransactionError - - interface TransactionError { - // TALER_EC_* unique error code. - // The action(s) offered and message displayed on the transaction item depend on this code. - ec: number; - - // English-only error hint, if available. - hint?: string; - - // Error details specific to "ec", if applicable/available - details?: any; - } - - .. ts:def:: WithdrawalDetails - - export type WithdrawalDetails = - | WithdrawalDetailsForManualTransfer - | WithdrawalDetailsForTalerBankIntegrationApi; - - .. ts:def:: WithdrawalDetailsForManualTransfer - - interface WithdrawalDetailsForManualTransfer { - type: "manual-transfer"; - - // Payto URIs that the exchange supports. - // Already contains the amount and message. - exchangePaytoUris: string[]; - - // Public key of the newly created reserve. - // Not useful for the UI, but required for integration testing. - reservePub: string; - } - - .. ts:def:: WithdrawalDetailsForTalerBankIntegrationApi - - interface WithdrawalDetailsForTalerBankIntegrationApi { - type: "taler-bank-integration-api"; - - // Set to true if the bank has confirmed the withdrawal, false if not. - // An unconfirmed withdrawal usually requires user-input and should be highlighted in the UI. - // See also bankConfirmationUrl below. - confirmed: boolean; - - // If the withdrawal is unconfirmed, this can include a URL for user - // initiated confirmation. - bankConfirmationUrl?: string; - } - - .. ts:def:: TransactionWithdrawal - - // This should only be used for actual withdrawals - // and not for tips that have their own transactions type. - interface TransactionWithdrawal extends Transaction { - type: string = "withdrawal", - - // Exchange that was withdrawn from. - exchangeBaseUrl: string; - - // Amount that has been subtracted from the reserve's balance for this withdrawal. - amountRaw: Amount; - - // Amount that actually was (or will be) added to the wallet's balance. - // Should always be shown as a positive amount. - amountEffective: Amount; +.. code-block:: console - // Further details - withdrawalDetails: WithdrawalDetails; - } + $ taler-wallet-cli --help + Usage: taler-wallet-cli COMMAND + + Command line interface for the GNU Taler wallet. + + Options: + -h, --help Show this message and exit. + --wallet-db=VALUE location of the wallet database file + --timetravel=VALUE modify system time by given offset in microseconds + --inhibit=VALUE Inhibit running certain operations, useful for debugging and testing. + --no-throttle Don't do any request throttling. + -v, --version + -V, --verbose Enable verbose output. + + Commands: + advanced Subcommands for advanced operations (only use if you know what you're doing!). + api Call the wallet-core API directly. + backup Subcommands for backups + balance Show wallet balance. + deposit Subcommands for depositing money to payto:// accounts + exchanges Manage exchanges. + handle-uri Handle a taler:// URI. + pending Show pending operations. + run-pending Run pending operations. + run-until-done Run until no more work is left. + testing Subcommands for testing GNU Taler deployments. + transactions Show transactions. + +Completing operations +--------------------- + +Note that the CLI does not run as a background daemon. When starting +operations that don't immediately finish, the wallet needs to be run explicitly +to finish any pending tasks: - .. ts:def:: TransactionPayment - interface TransactionPayment extends Transaction { - type: string = "payment", +.. code-block:: console - // Additional information about the payment. - info: OrderShortInfo; + # Do one attempt to finish all pending operations + $ taler-wallet-cli run-pending - // Wallet-internal end-to-end identifier for the payment - // (assigned before the order is even downloaded, thus the name). - proposalId: string; + # Run until all work is done + $ taler-wallet-cli run-until-done - // The current status of this payment. - status: PaymentStatus; +Resetting the wallet +-------------------- - // Amount that must be paid for the contract - amountRaw: Amount; +The wallet can be reset by deleting its database file. By default, the database file +is ``$HOME/.talerwalletdb.json``. - // Amount that was paid, including deposit, wire and refresh fees. - // Should always be shown as a negative amount. - amountEffective: Amount; - } - .. ts:def:: OrderShortInfo +Handling taler:// URIs +---------------------- - interface OrderShortInfo { - // Order ID, uniquely identifies the order within a merchant instance - orderId: string; +Many interactions with the Taler wallet happen by scanning QR codes or special +headers on Websites. To emulate this with the command line interface, run the following +command: - // More information about the merchant - merchant: Merchant; +.. code-block:: console - // Summary of the order, given by the merchant - summary: string; + $ taler-wallet-cli handle-uri $URI - // Map from IETF BCP 47 language tags to localized summaries - summary_i18n?: { [lang_tag: string]: string }; - // List of products that are part of the order - products: Product[]; +Manual withdrawing +------------------ - // URL of the fulfillment, given by the merchant - fulfillmentUrl?: string; +.. code-block:: console - // Message shown to the user after the payment is complete. - fulfillmentMessage?: string; + $ taler-wallet-cli advanced withdraw-manually \ + --exchange https://exchange.eurint.taler.net/ \ + --amount EUR:5 - // Map from IETF BCP 47 language tags to localized fulfillment messages - fulfillmentMessage_i18n: { [lang_tag: string]: string }; - } - .. ts:def:: PaymentStatus +P2P push payments +----------------- - enum PaymentStatus { - // Explicitly aborted after timeout / failure - Aborted = "aborted", +The following code generates a P2P push transaction over 1 CHF +with an expiration time of 30 days (assuming the wallet has a +sufficient balance): - // Payment failed, wallet will auto-retry. - // User should be given the option to retry now / abort. - Failed = "failed", +.. code-block:: console - // Paid successfully - Paid = "paid", + $ taler-wallet-cli p2p initiate-push-debit \ + --purse-expiration="30 d" \ + --summary="The summary" \ + CHF:1 - // Only offered, user must accept / decline - Offered = "offered", +The final URL can then be found in the transaction list: - // User accepted, payment is processing. - Accepted = "accepted", - } +.. code-block:: console - .. ts:def:: TransactionRefund + $ taler-wallet-cli transactions - interface TransactionRefund extends Transaction { - type: string = "refund", +Background wallet +----------------- - // ID for the transaction that is refunded - refundedTransactionId: string; +A wallet can be launched in the background: - // Additional information about the refunded payment - info: OrderShortInfo; +.. code-block:: console - // Part of the refund that couldn't be applied because the refund permissions were expired - amountInvalid: Amount; + $ taler-wallet-cli advanced serve & - // Amount that has been refunded by the merchant. - // Corresponds to amountRefundGranted from the applyRefund response. - amountRaw: Amount; +You can then run various Taler operations faster against +this one persistent instance: - // Amount will be added to the wallet's balance after fees and refreshing. - // Should always be shown as a positive amount. - amountEffective: Amount; - } +.. code-block:: console - .. ts:def:: TransactionTip + $ taler-wallet-cli --wallet-connection=wallet-core.sock ... - interface TransactionTip extends Transaction { - type: string = "tip", +Here ``...`` needs to be changed to the commando to run. +Make sure to run - // The current status of this tip. - status: TipStatus; +.. code-block:: console - // Exchange that the tip will be (or was) withdrawn from - exchangeBaseUrl: string; + $ taler-wallet-cli --wallet-connection=wallet-core.sock \ + run-until-done - // More information about the merchant that sent the tip - merchant: Merchant; +to wait for pending transactions to complete. - // Raw amount of the tip, without extra fees that apply - amountRaw: Amount; - // Amount will be (or was) added to the wallet's balance after fees and refreshing. - // Should always be shown as a positive amount. - amountEffective: Amount; - } +Testing an exchange deployment +------------------------------ - .. ts:def:: TipStatus +The following series of commands can be used to check that an exchange deployment +is functional: - enum TipStatus { - // Only offered, user must accept / decline - Offered = "offered", +.. code-block:: console - // User accepted, tip is processing. - Accepted = "accepted", + # This will now output a payto URI that money needs to be sent to in order to allow withdrawal + # of taler coins + $ taler-wallet-cli advanced withdraw-manually --exchange $EXCHANGE_URL --amount EUR:10.50 - // User declined. - Declined = "declined", + # Show the status of the manual withdrawal operation + $ taler-wallet-cli transactions - // Received successfully - Received = "received", - } + # Once the transfer has been made, try completing the withdrawal + $ taler-wallet-cli run-pending - .. ts:def:: TransactionRefresh + # Check status of transactions and show balance + $ taler-wallet-cli transactions + $ taler-wallet-cli balance - // A transaction shown for refreshes that are not associated to other transactions - // such as a refresh necessary before coin expiration. - // It should only be returned by the API if the effective amount is different from zero. - interface TransactionRefresh extends Transaction { - type: string = "refresh", + # Now, directly deposit coins with the exchange into a target account + # (Usually, a payment is made via a merchant. The wallet provides + # this functionality for testing.) + $ taler-wallet-cli deposit create EUR:5 payto://iban/$IBAN - // Exchange that the coins are refreshed with - exchangeBaseUrl: string; + # Check if transaction was successful. + # (If not, fix issue with exchange and run "run-pending" command again) + $ taler-wallet-cli transactions - // Raw amount that is refreshed - amountRaw: Amount; + # The wallet can also track if the exchange wired the money to the merchant account. + # The "deposit group id" can be found in the output of the transactions list. + $ taler-wallet-cli deposit track $DEPOSIT_GROUP_ID - // Amount that will be paid as fees for the refresh. - // Should always be shown as a negative amount. - amountEffective: Amount; - } +.. _withdraw-simulation: -:Name: ``"deleteTransaction"`` -:Description: Delete a transaction by ID. -:Request: - .. ts:def:: DeleteTransactionRequest +Paying for an order +=================== - interface DeleteTransactionRequest { - // Transaction ID (opaque!) as returned in - // the transaction list response. - transactionId: string; - } -:Response: Returns an empty object +.. note:: -Refunds -------- + This section is in dire need for some editing... -:Name: ``"applyRefund"`` -:Description: Process a refund from a ``taler://refund`` URI. -:Request: - .. ts:def:: WalletApplyRefundRequest +This section explains how to pay for an order in a scenario where the fiat bank +is simulated. The simulation takes place by crafting ad-hoc XML files as if the +bank would have issued them. Such XML files carry information about incoming payments +to the regional currency master bank account. Finally, the XML files are passed +to LibEuFin nexus via a convenient CLI method. The responsible script for such +simulation is ``withdraw.sh``. - interface WalletApplyRefundRequest { - talerRefundUri: string; - } -:Response: - .. ts:def:: WalletApplyRefundResponse +Run ``./withdraw.sh`` without any arguments. Assuming that you ran the command +as the ``test-user``, after the execution, 5 units of the regional currency should +be found in the CLI wallet owned by ``test-user``. - interface WalletApplyRefundResponse { - // Identifier for the purchase that was refunded - // DEPRECATED: Will disappear soon. - contractTermsHash: string; - amountEffectivePaid: Amount; +Check it with: - amountRefundGranted: Amount; +.. code-block:: console - amountRefundGone: Amount; + $ taler-wallet-cli balance - pendingAtExchange: boolean; +If so, call the wallet in the following way to finally pay for the order just created: - // Short info about the order being refunded. - info: OrderShortInfo; - } +.. code-block:: console -Exchange Management -------------------- + $ taler-wallet-cli handle-uri "$TALER_PAY_URI" -List Exchanges -~~~~~~~~~~~~~~ +.. note:: -:Name: ``"listExchanges"`` -:Description: - List all exchanges. -:Response: - .. ts:def:: ExchangesListResponse + Reset the state before going to production, as it impacts the way nexus + asks records to the bank. In particular, delete: any database and the + files ``config/user.conf`` and ``config/internal.conf``, and finally run + ``./main.sh`` again. - interface ExchangesListResponse { - exchanges: ExchangeListItem[]; - } - .. ts:def:: ExchangeListItem - interface ExchangeListItem { - exchangeBaseUrl: string; - currency: string; - paytoUris: string[]; - } -Add Exchange -~~~~~~~~~~~~ -:Name: ``"addExchange"`` -:Description: - Add an exchange. -:Request: - .. ts:def:: ExchangeAddRequest +APIs and Data Formats +===================== - interface ExchangeAddRequest { - exchangeBaseUrl: string; - } -:Response: - On success, the response is an `ExchangeListItem`. +Envelope Format +--------------- +All API responses and notifications are returned in the +following envelope: -Force Exchange Update -~~~~~~~~~~~~~~~~~~~~~ +.. ts:def:: WalletResponseEnvelope -:Name: ``"forceUpdateExchange"`` -:Description: - Force updating an exchange. - Re-queries current cryptographic key material, wire information - and terms of service from the exchange. Also applies denomination revocations - if applicable. -:Request: - .. ts:def:: ExchangeForceUpdateRequest + type WalletResponseEnvelope = + | WalletSuccess + | WalletError + | WalletNotification - interface ExchangeForceUpdateRequest { - exchangeBaseUrl: string; - } -:Response: - On success, the response is an `ExchangeListItem`. +.. ts:def:: WalletSuccess + export interface WalletSuccess { + type: "response"; + operation: string; + // ID to correlate success response to request + id: string; + // Result type depends on operation + result: unknown; + } -Get Terms of Service -~~~~~~~~~~~~~~~~~~~~ +.. ts:def:: WalletError -:Name: ``"getExchangeTos"`` -:Description: - Get the exchange's current ToS and which version of the ToS (if any) - the user has accepted. -:Request: - .. ts:def:: ExchangeGetTosRequest + export interface WalletError { + type: "error"; + operation: string; + // ID to correlate error response to request + id: string; + error: WalletErrorInfo; + } - interface ExchangeGetTosRequest { - exchangeBaseUrl: string; - } -:Response: - .. ts:def:: ExchangeGetTosResult +.. ts:def:: WalletNotification - interface GetExchangeTosResult { - // Markdown version of the current ToS. - content: string; + export interface WalletSuccess { + type: "notification"; - // Version tag of the current ToS. - currentEtag: string; + // actual type is WalletNotification, + // to be documented here + payload: any; + } - // Version tag of the last ToS that the user has accepted, - // if any. - acceptedEtag: string | undefined; - } +.. ts:def:: WalletErrorInfo -Set Accepted Terms of Service Version -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + export interface WalletErrorInfo { + // Numeric error code defined defined in the + // GANA gnu-taler-error-codes registry. + talerErrorCode: number; -:Name: ``"setExchangeTosAccepted"`` -:Description: - Store that the user has accepted a version of the exchange's ToS. -:Request: - .. ts:def:: ExchangeSetTosAccepted + // English description of the error code. + talerErrorHint: string; - interface ExchangeGetTosRequest { - exchangeBaseUrl: string; - etag: string; - } -:Response: - On success, the response is an empty object. + // English diagnostic message that can give details + // for the instance of the error. + message: string; + // Error details, type depends + // on talerErrorCode + details: unknown; + } Withdrawal ---------- @@ -657,464 +408,6 @@ A typical API sequence for *manual* withdrawals can for example look like this: #. ``"acceptManualWithdrawal"`` after the user confirmed withdrawal with associated fees -Get Details For Bank-integrated Withdrawal -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:Name: ``"getWithdrawalDetailsForUri"`` -:Description: - Get information about exchanges for a bank-integrated withdrawal from a ``taler://withdraw`` URI. -:Request: - .. ts:def:: GetWithdrawalUriDetailsRequest - - interface GetWithdrawalUriDetailsRequest { - talerWithdrawUri: string; - } -:Response: - .. ts:def:: WithdrawalDetailsForUri - - interface WithdrawalDetailsForUri { - // The amount that the user wants to withdraw - amount: Amount; - - // Exchange suggested by the wallet - defaultExchangeBaseUrl?: string; - - // A list of exchanges that can be used for this withdrawal - possibleExchanges: ExchangeListItem[]; - } - -Get Withdrawal Details -~~~~~~~~~~~~~~~~~~~~~~ - -:Name: ``"getWithdrawalDetailsForAmount"`` -:Description: - Get information about fees and exchange for a withdrawal of a given amount. - Can be used for both bank-integrated and manual withdrawals. -:Request: - .. ts:def:: WithdrawalDetailsRequest - - interface WithdrawalDetailsRequest { - exchangeBaseUrl: string; - amount: Amount; - } -:Response: - .. ts:def:: WithdrawalDetails - - interface WithdrawalDetails { - // Did the user accept the current version of the exchange's terms of service? - tosAccepted: boolean; - - // Amount that will be transferred to the exchange. - amountRaw: Amount; - - // Amount that will be added to the user's wallet balance. - amountEffective: Amount; - } - -Accept Bank-integrated Withdrawal -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:Name: ``"acceptWithdrawal"`` -:Description: - Accept a bank-integrated withdrawal, where the bank transfers funds automatically. -:Request: - .. ts:def:: GetManualWithdrawalDetailsRequest - - interface AcceptWithdrawalRequest { - talerWithdrawUri: string; - exchangeBaseUrl: string; - } -:Response: - .. ts:def:: AcceptWithdrawalResponse - - interface AcceptWithdrawalResponse { - // a URL for user initiated confirmation. - bankConfirmationUrl?: string; - } - -Accept Manual Withdrawal -~~~~~~~~~~~~~~~~~~~~~~~~ - -:Name: ``"acceptManualWithdrawal"`` -:Description: - Accept a manual withdrawal, where the user has to transfer funds manually. -:Request: - .. ts:def:: AcceptManualWithdrawalRequest - - interface AcceptManualWithdrawalRequest { - exchangeBaseUrl: string; - amount: Amount; - } -:Response: - .. ts:def:: AcceptManualWithdrawalResponse - - interface AcceptManualWithdrawalResponse { - // Payto URIs to fund the withdrawal, - // with amount and message provided. - exchangePaytoUris: string[]; - } - -Deposits --------- - -Deposits are direct payments into a payment target (given via -a payto URI). They don't involve a merchant. - -:Name: ``"createDepositGroup"`` -:Description: - Deposit funds directly into a payment target. -:Request: - .. ts:def:: CreateDepositGroupRequest - - interface CreateDepositGroupRequest { - depositPaytoUri: string; - amount: Amount; - } -:Response: - .. ts:def:: CreateDepositGroupResponse - - interface CreateDepositGroupResponse { - depositGroupId: string; - } - - -Payments --------- - -Prepare Pay -~~~~~~~~~~~ - -:Name: ``"preparePay"`` -:Description: - Fetch information about a payment request from a merchant. -:Request: - .. ts:def:: PreparePayRequest - - interface PreparePayRequest { - talerPayUri: string; - } -:Response: - .. ts:def:: PreparePayResponse - - type PreparePayResponse = - | PreparePayPaymentPossibleResponse - | PreparePayAlreadyConfirmedResponse - | PreparePayInsufficientBalanceResponse; - - .. ts:def:: PreparePayPaymentPossibleResponse - - interface PreparePayPaymentPossibleResponse { - status: "payment-possible"; - - proposalId: string; - - // Verbatim contract terms as generated by the merchant. - contractTerms: ContractTerms; - - // Amount that the merchant is asking for. - amountRaw: Amount; - - // Amount that will effectively be subtracted from the wallet's - // balance when accepting this proposal. - amountEffective: Amount; - } - - .. ts:def:: PreparePayInsufficientBalanceResponse - - interface PreparePayInsufficientBalanceResponse { - status: "insufficient-balance"; - - proposalId: string; - - // Amount that the merchant is asking for. - amountRaw: Amount; - - // Verbatim contract terms as generated by the merchant. - contractTerms: ContractTerms; - } - - .. ts:def:: PreparePayAlreadyConfirmedResponse - - interface PreparePayAlreadyConfirmedResponse { - status: "already-confirmed"; - - proposalId: string; - - // Did the payment succeed? - paid: boolean; - - // Amount that the merchant is asking for. - amountRaw: Amount; - - // Amount that will be subtracted from the wallet balance - amountEffective: Amount; - - // Verbatim contract terms as generated by the merchant. - contractTerms: ContractTerms; - } - - -Confirm Payment -~~~~~~~~~~~~~~~ - -:Name: ``"confirmPay"`` -:Description: - Confirm making a payment. - -:Request: - .. ts:def:: GetManualWithdrawalDetailsRequest - - interface ConfirmPayRequest { - proposalId: string; - } -:Response: - .. ts:def:: ConfirmPayResultDone - - interface ConfirmPayResultDone { - type: "done"; - - contractTerms: ContractTerms; - } - - .. ts:def:: ConfirmPayResultPending - - // Payment was marked as confirmed, - // but the attempt(s) to pay were not successful yet. - interface ConfirmPayPending { - type: "pending"; - - lastError: TransactionError; - } - - .. ts:def:: ConfirmPayResult - - type ConfirmPayResult = - | ConfirmPayResultDone; - | ConfirmPayResultPending; - -Abort Failed Payment -~~~~~~~~~~~~~~~~~~~~ - -:Name: ``"abortFailedPayWithRefund"`` -:Description: - Abort a failed payment and try to get a refund for the - partially paid amount. -:Request: - .. ts:def:: AbortPayWithRefundRequest - - export interface AbortPayWithRefundRequest { - proposalId: string; - } -:Response: - On success, the response is an empty object. - -Tipping API Calls ------------------ - -Preparing a tip -~~~~~~~~~~~~~~~ - -:Name: ``"prepareTip"`` -:Description: - Prepare to accept a tip based in a ``taler://tip`` URI. -:Request: - .. ts:def:: PrepareTipRequest - - interface PrepareTipRequest { - talerTipUri: string; - } -:Response: - .. ts:def:: PrepareTipResult - - interface PrepareTipResult { - // Unique ID for the tip assigned by the wallet. - // Typically different from the merchant-generated tip ID. - walletTipId: string; - - // Has the tip already been accepted? - accepted: boolean; - tipAmountRaw: Amount; - tipAmountEffective: Amount; - exchangeBaseUrl: string; - expirationTimestamp: Timestamp; - } - - -Accepting a tip -~~~~~~~~~~~~~~~ - -:Name: ``"acceptTip"`` -:Description: - Prepare to accept a tip based in a ``taler://tip`` URI. -:Request: - .. ts:def:: AcceptTipRequest - - interface AcceptTipRequest { - walletTipId: string; - } -:Response: - On success, the response is an empty object. - -Testing API calls ------------------ - -The following API calls are useful for testing. - -Withdraw balance from the TESTKUDOS environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:Name: ``"withdrawTestkudos"`` -:Description: - Withdraw a balance from the ``TESTKUDOS`` environment. -:Request: - The request parameters are ignored. -:Response: - On success, the response is an empty object. - -Withdraw balance from a test environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:Name: ``"withdrawTestBalance"`` -:Description: - Withdraw a balance from a test environment. -:Request: - .. ts:def:: WithdrawTestBalanceRequest - - interface WithdrawTestBalanceRequest { - amount: string; - bankBaseUrl: string; - exchangeBaseUrl: string; - } -:Response: - On success, the response is an empty object. - -Run integration test -~~~~~~~~~~~~~~~~~~~~ - -:Name: ``"runIntegrationTest"`` -:Description: - Run a basic integration test that does a withdrawal, payment, - refund and again a payment. Useful to generate test data - in the integration tests of other components. -:Request: - .. ts:def:: IntegrationTestArgs - - interface IntegrationTestArgs { - exchangeBaseUrl: string; - bankBaseUrl: string; - merchantBaseUrl: string; - merchantApiKey: string; - amountToWithdraw: string; - amountToSpend: string; - } -:Response: - On success, the response is an empty object. - -Make a test payment -~~~~~~~~~~~~~~~~~~~ - -:Name: ``"testPay"`` -:Description: - Make a test payment with existing funds. -:Request: - .. ts:def:: TestPayArgs - - interface TestPayArgs { - merchantBaseUrl: string; - merchantApiKey: string; - amount: string; - summary: string; - } - - -Dump all coins to JSON -~~~~~~~~~~~~~~~~~~~~~~ - -:Name: ``"dumpCoins"`` -:Description: - Make a test payment with existing funds. -:Request: - The request object is ignored. -:Response: - .. code:: ts - - interface CoinDumpJson { - coins: Array<{ - /** - * The coin's denomination's public key. - */ - denom_pub: string; - /** - * Hash of denom_pub. - */ - denom_pub_hash: string; - /** - * Value of the denomination (without any fees). - */ - denom_value: string; - /** - * Public key of the coin. - */ - coin_pub: string; - /** - * Base URL of the exchange for the coin. - */ - exchange_base_url: string; - /** - * Remaining value on the coin, to the knowledge of - * the wallet. - */ - remaining_value: string; - /** - * Public key of the parent coin. - * Only present if this coin was obtained via refreshing. - */ - refresh_parent_coin_pub: string | undefined; - /** - * Public key of the reserve for this coin. - * Only present if this coin was obtained via refreshing. - */ - withdrawal_reserve_pub: string | undefined; - /** - * Is the coin suspended? - * Suspended coins are not considered for payments. - */ - coin_suspended: boolean; - }>; - } - - -Suspend/unsuspend a coin -~~~~~~~~~~~~~~~~~~~~~~~~ - -A suspended coin will not be used by the wallet for payments. -This functionality is only used for testing. - -:Name: ``"setCoinSuspended"`` -:Description: - Make a test payment with existing funds. -:Request: - .. ts:def:: SetCoinSuspendedRequest - - interface SetCoinSuspendedRequest { - coinPub: string; - suspended: boolean; - } -:Request: - On success, the response is an empty object. - -Global Errors -------------- - -* Backup/Sync/Anastasis failed -* refresh after pay failed for multiple attempts - (depending on online status) -* scheduled refresh (to avoid expiration) failed -* general recoups (?) -* failed recoup -* (maybe) fatal errors during withdrawal -* pending refund failed permanently (?) - Integration Tests ================= @@ -1205,7 +498,6 @@ Things we still need tests for: Or when the merchant is not reachable? Or the bank? This can be tested by temporarily killing those services. * How does the wallet deal with processing the same ``taler://(pay|withdraw)`` URI twice? -* Test tipping (accepting/refusing a tip) * Test refunds * Test for :ref:`session-based payments <repurchase>` * Test case for auto-refunds |