From 7d1b635fdd3472d314ccd32fe0bde03eb2f5ae5a Mon Sep 17 00:00:00 2001 From: Torsten Grote Date: Mon, 20 Jul 2020 11:50:08 -0300 Subject: Fix wallet API docs and adjust withdraw API --- taler-wallet.rst | 183 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 104 insertions(+), 79 deletions(-) (limited to 'taler-wallet.rst') diff --git a/taler-wallet.rst b/taler-wallet.rst index 6dd37749..604203b1 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -219,6 +219,8 @@ Transactions are all operations or events that are affecting the balance. | WithdrawalDetailsForManualTransfer | WithdrawalDetailsForTalerBankIntegrationApi; + .. ts:def:: WithdrawalDetailsForManualTransfer + interface WithdrawalDetailsForManualTransfer { type: "manual-transfer"; @@ -227,6 +229,8 @@ Transactions are all operations or events that are affecting the balance. exchangePaytoUris: string[]; } + .. ts:def:: WithdrawalDetailsForTalerBankIntegrationApi + interface WithdrawalDetailsForTalerBankIntegrationApi { type: "taler-bank-integration-api"; @@ -420,8 +424,11 @@ Refunds contractTermsHash: string; } -Exchange Management: List Exchanges ------------------------------------ +Exchange Management +------------------- + +List Exchanges +~~~~~~~~~~~~~~ :Name: ``"listExchanges"`` :Description: @@ -429,9 +436,9 @@ Exchange Management: List Exchanges :CLI: ``taler-wallet-cli exchanges list`` :Response: - .. ts:def:: ExchangesListRespose + .. ts:def:: ExchangesListResponse - interface ExchangesListRespose { + interface ExchangesListResponse { exchanges: ExchangeListItem[]; } @@ -443,8 +450,8 @@ Exchange Management: List Exchanges paytoUris: string[]; } -Exchange Management: Add Exchange ---------------------------------- +Add Exchange +~~~~~~~~~~~~ :Name: ``"addExchange"`` :Description: @@ -458,10 +465,34 @@ Exchange Management: Add Exchange exchangeBaseUrl: string; } :Response: - On success, the response is an empty object. + On success, the response is an `ExchangeListItem`. + + +Get Suggested Exchanges +~~~~~~~~~~~~~~~~~~~~~~~ + +:Name: ``"getSuggestedExchanges"`` +:Description: + Get default exchange and the bank's suggested exchange for a given withdrawal URI. +:Request: + .. ts:def:: ExchangeGetSuggestedRequest + + interface ExchangeGetSuggestedRequest { + talerWithdrawUri: string; + } +:Response: + .. ts:def:: ExchangeGetSuggestedResponse + + interface ExchangeGetSuggestedResponse { + // Exchange suggested by the wallet + defaultExchange?: string; -Exchange Management: Get Terms of Service ------------------------------------------ + // Exchange suggested by the bank + bankSuggestedExchange?: string; + } + +Get Terms of Service +~~~~~~~~~~~~~~~~~~~~ :Name: ``"getExchangeTos"`` :Description: @@ -478,7 +509,7 @@ Exchange Management: Get Terms of Service :Response: .. ts:def:: ExchangeGetTosResult - export interface GetExchangeTosResult { + interface GetExchangeTosResult { // Markdown version of the current ToS. tos: string; @@ -490,8 +521,8 @@ Exchange Management: Get Terms of Service acceptedEtag: string | undefined; } -Exchange Management: Set Accepted Terms of Service Version ----------------------------------------------------------- +Set Accepted Terms of Service Version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :Name: ``"setExchangeTosAccepted"`` :Description: @@ -509,8 +540,11 @@ Exchange Management: Set Accepted Terms of Service Version On success, the response is an empty object. -Withdrawal: Withdraw balance from test environment --------------------------------------------------- +Withdrawal +---------- + +Withdraw balance from test environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :Name: ``"withdrawTestkudos"`` :Description: @@ -523,93 +557,57 @@ Withdrawal: Withdraw balance from test environment On success, the response is an empty object. -Withdrawal: Get Manual Withdrawal Info --------------------------------------- +Get Withdrawal Info For Bank-integrated Withdrawal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:Name: ``"getWithdrawalDetailsForAmount"`` +:Name: ``"getWithdrawalDetailsForUri"`` :Description: - Get information about fees and exchange for a manual withdrawal of a given amount. -:CLI: - ``taler-wallet-cli advanced manual-withdrawal-details $URL $AMOUNT`` + Get information about fees for a bank-integrated withdrawal from a taler://withdraw URI. :Request: .. ts:def:: GetManualWithdrawalDetailsRequest - interface ExchangeAddRequest { + interface GetManualWithdrawalDetailsRequest { + talerWithdrawUri: string; exchangeBaseUrl: string; - amount: string; } :Response: - .. ts:def:: ManualWithdrawalDetails + .. ts:def:: WithdrawalDetailsForUri - export interface ManualWithdrawalDetails { + interface WithdrawalDetailsForUri { // Did the user accept the current version of the exchange's // terms of service? tosAccepted: boolean; - // Amount that the user will transfer to the exchange. - rawAmount: AmountString; + // Amount that the bank will transfer to the exchange. + rawAmount: Amount; // Amount that will be added to the user's wallet balance. - effectiveAmount: AmountString; - - // Ways to pay the exchange. - paytoUris: string[]; + effectiveAmount: Amount; } -Withdrawal: Get Withdrawal Info For Bank-integrated Withdrawal --------------------------------------------------------------- +Accept Bank-integrated Withdrawal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:Name: ``"getWithdrawalDetailsForUri"`` +:Name: ``"acceptWithdrawal"`` :Description: - Get information about fees and exchange for a bank-integrated withdrawal - from a taler://withdraw URI. + Accept a bank-integrated withdrawal, where the bank transfers funds automatically. :Request: .. ts:def:: GetManualWithdrawalDetailsRequest - interface ExchangeAddRequest { + interface AcceptWithdrawalRequest { talerWithdrawUri: string; - // Selected exchange, if an exchange has been selected already - // by the user (or preselected by the wallet) - selectedExchange?: string; - } -:Response: - .. ts:def:: WithdrawalDetailsForUri - - export interface WithdrawalDetailsForUri { - // Did the user accept the current version of the exchange's - // terms of service? - tosAccepted: boolean; - - // Exchange suggested by the bank - bankSuggestedExchange?: string; - } - -Withdrawal: Accept Manual Withdrawal ------------------------------------- - -:Name: ``"acceptManualWithdrawal"`` -:Description: - Accept a manual withdrawal, where the user has to transfer funds manually. -:CLI: - ``taler-wallet-cli advanced withdraw-manually --exchange $EXCHANGE --amount $AMOUNT`` -:Request: - .. ts:def:: AcceptManualWithdrawalRequest - - interface AcceptManualWithdrawalRequest { exchangeBaseUrl: string; - amount: AmountString; } :Response: - .. ts:def:: AcceptManualWithdrawalResponse + .. ts:def:: AcceptWithdrawalResponse - interface AcceptManualWithdrawalResponse { - // Payto URIs to fund the withdrawal, - // with amount and message provided. - exchangePaytoUris: string[]; + interface AcceptWithdrawalResponse { + // a URL for user initiated confirmation. + bankConfirmationUrl?: string; } -Withdrawal: Get Manual Withdrawal Info --------------------------------------- +Get Manual Withdrawal Info +~~~~~~~~~~~~~~~~~~~~~~~~~~ :Name: ``"getWithdrawalDetailsForAmount"`` :Description: @@ -626,16 +624,16 @@ Withdrawal: Get Manual Withdrawal Info :Response: .. ts:def:: ManualWithdrawalDetails - export interface ManualWithdrawalDetails { + interface ManualWithdrawalDetails { // Did the user accept the current version of the exchange's // terms of service? tosAccepted: boolean; // Amount that the user will transfer to the exchange. - rawAmount: AmountString; + rawAmount: Amount; // Amount that will be added to the user's wallet balance. - effectiveAmount: AmountString; + effectiveAmount: Amount; // Ways to pay the exchange. // Does not include the amount and message, as the @@ -643,15 +641,42 @@ Withdrawal: Get Manual Withdrawal Info paytoUris: string[]; } -Payments: Prepare Pay ---------------------- +Accept Manual Withdrawal +~~~~~~~~~~~~~~~~~~~~~~~~ + +:Name: ``"acceptManualWithdrawal"`` +:Description: + Accept a manual withdrawal, where the user has to transfer funds manually. +:CLI: + ``taler-wallet-cli advanced withdraw-manually --exchange $EXCHANGE --amount $AMOUNT`` +: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[]; + } + +Payments +-------- + +Prepare Pay +~~~~~~~~~~~ :Name: ``"preparePay"`` :Description: Fetch information about a payment request from a merchant. -Payments: Confirm Payment -------------------------- +Confirm Payment +~~~~~~~~~~~~~~~ :Name: ``"confirmPay"`` :Description: -- cgit v1.2.3