From 7d63c95d0f779a2ade14896af9d4b304e038f826 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 8 Feb 2024 16:51:24 +0100 Subject: remove reward-related APIs and design considerations --- core/api-merchant.rst | 541 +------------------------------------------------- 1 file changed, 1 insertion(+), 540 deletions(-) (limited to 'core/api-merchant.rst') diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 652c7303..46392118 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -199,8 +199,7 @@ This section describes (public) endpoints that wallets must be able to interact with directly (without HTTP-based authentication). These endpoints are used to process payments (claiming an order, paying for the order, checking payment/refund status and aborting payments), -process refunds (checking refund status, obtaining the refund), -and to pick up rewards. +and to process refunds (checking refund status, obtaining the refund). Claiming an order @@ -837,111 +836,6 @@ the contract. Refunds must be approved by the merchant's business logic. } -Picking up rewards ------------------- - -Rewards are a way for wallets to obtain e-cash from -a website. - -.. http:get:: [/instances/$INSTANCE]/rewards/$REWARD_ID - - Handle request from wallet to provide details about a reward. - - This endpoint typically also supports requests with the "Accept" header - requesting "text/html". In this case, an HTML response suitable for - triggering the interaction with the wallet is returned. If the backend - installation does not include the required HTML templates, a 406 status - code is returned. - - **Response:** - - :http:statuscode:`200 OK`: - A reward is being returned. The backend responds with a `RewardInformation`. - :http:statuscode:`404 Not found`: - The reward identifier is unknown. - :http:statuscode:`406 Not acceptable`: - The merchant backend could not load the template required to generate a reply in the desired format. (Likely HTML templates were not properly installed.) - :http:statuscode:`410 Gone`: - A reward has been fully claimed. The JSON reply still contains the `RewardInformation`. - - .. ts:def:: RewardInformation - - interface RewardInformation { - - // Exchange from which the reward will be withdrawn. Needed by the - // wallet to determine denominations, fees, etc. - exchange_url: string; - - // URL where to go after obtaining the reward. - next_url: string; - - // (Remaining) amount of the reward (including fees). - reward_amount: Amount; - - // Timestamp indicating when the reward is set to expire (may be in the past). - // Note that rewards that have expired MAY also result in a 404 response. - expiration: Timestamp; - } - - -.. http:post:: [/instances/$INSTANCE]/rewards/$REWARD_ID/pickup - - Handle request from wallet to pick up a reward. - - **Request:** - - The request body is a `RewardPickupRequest` object. - - **Response:** - - :http:statuscode:`200 OK`: - A reward is being returned. The backend responds with a `RewardResponse`. - :http:statuscode:`401 Unauthorized`: - The reward amount requested exceeds the reward. - :http:statuscode:`404 Not found`: - The reward identifier is unknown. - :http:statuscode:`409 Conflict`: - Some of the denomination key hashes of the request do not match those currently available from the exchange (hence there is a conflict between what the wallet requests and what the merchant believes the exchange can provide). - :http:statuscode:`410 Gone`: - The reward has expired. - - .. ts:def:: RewardPickupRequest - - interface RewardPickupRequest { - - // List of planchets the wallet wants to use for the reward. - planchets: PlanchetDetail[]; - } - - .. ts:def:: PlanchetDetail - - interface PlanchetDetail { - // Hash of the denomination's public key (hashed to reduce - // bandwidth consumption). - denom_pub_hash: HashCode; - - // Coin's blinded public key. - coin_ev: CoinEnvelope; - } - - .. ts:def:: RewardResponse - - interface RewardResponse { - - // Blind RSA signatures over the planchets. - // The order of the signatures matches the planchets list. - blind_sigs: BlindSignature[]; - } - - .. ts:def:: BlindSignature - - interface BlindSignature { - - // The (blind) RSA signature. Still needs to be unblinded. - blind_sig: BlindedRsaSignature; - } - - ------------------- Instance management ------------------- @@ -2698,439 +2592,6 @@ once we got a reply from the exchange. The transfer cannot be deleted anymore. -.. _api-rewards: - ------------------------ -Backend: Giving rewards ------------------------ - -.. note:: - - This API is deprecated as of protocol v8. - -Rewards are a way for websites to give small amounts of e-cash to visitors (for -example as a financial reward for providing information or viewing -advertisements). Rewards are non-contractual: neither merchant nor consumer -have any contractual information about the other party as a result of the -reward. - - -Create reserve --------------- - -.. note:: - - This API is deprecated as of protocol v8. - -Reserves are basically funds a merchant has provided to an exchange for a -rewards campaign. Each reserve has a limited lifetime (say 2--4 weeks). Any -funds not used to reward customers will automatically be wired back from the -exchange to the originating account. - -Before handing out rewards, a merchant must tell the backend to set up a -reserve. The backend will return a reserve public key which must be used as -the wire transfer subject when wiring the reward campaign funds to the -exchange. - -.. http:post:: [/instances/$INSTANCE]/private/reserves - - Create a reserve for rewards. - - This request is **not** idempotent. However, while repeating - it will create another reserve, that is generally pretty harmless - (assuming only one of the reserves is filled with a wire transfer). - Clients may want to eventually delete the unused reserves to - avoid clutter. - - **Request:** - - The request body is a `ReserveCreateRequest` object. - - **Response:** - - :http:statuscode:`200 OK`: - The backend is waiting for the reserve to be established. The merchant - must now perform the wire transfer indicated in the `ReserveCreateConfirmation`. - :http:statuscode:`408 Request timeout`: - The exchange did not respond on time. - :http:statuscode:`409 Conflict`: - The exchange does not support the requested wire method or does not allow rewards. - :http:statuscode:`502 Bad gateway`: - We could not obtain ``/wire`` details from the specified exchange base URL. - :http:statuscode:`504 Gateway timeout`: - The merchant's interaction with the exchange took too long. - The client might want to try again later. - - .. ts:def:: ReserveCreateRequest - - interface ReserveCreateRequest { - // Amount that the merchant promises to put into the reserve. - initial_balance: Amount; - - // Exchange the merchant intends to use for rewards. - exchange_url: string; - - // Desired wire method, for example "iban" or "x-taler-bank". - wire_method: string; - } - - .. ts:def:: ReserveCreateConfirmation - - interface ReserveCreateConfirmation { - // Public key identifying the reserve. - reserve_pub: EddsaPublicKey; - - // Wire accounts of the exchange where to transfer the funds. - accounts: WireAccount[]; - } - -.. http:get:: [/instances/$INSTANCE]/private/reserves - - Obtain list of reserves that have been created for rewards. - - **Request:** - - :query after: *Optional*. Only return reserves created after the given timestamp in milliseconds. - :query active: *Optional*. Only return active/inactive reserves depending on the boolean given. - :query failures: *Optional*. Only return reserves where we disagree with the exchange about the initial balance. - - **Response:** - - :http:statuscode:`200 OK`: - Returns a list of known reward reserves. - The body is a `RewardReserveStatus`. - - .. ts:def:: RewardReserveStatus - - interface RewardReserveStatus { - // Array of all known reserves (possibly empty!). - reserves: ReserveStatusEntry[]; - } - - .. ts:def:: ReserveStatusEntry - - interface ReserveStatusEntry { - // Public key of the reserve. - reserve_pub: EddsaPublicKey; - - // Timestamp when it was established. - creation_time: Timestamp; - - // Timestamp when it expires. - expiration_time: Timestamp; - - // Initial amount as per reserve creation call. - merchant_initial_amount: Amount; - - // Initial amount as per exchange, 0 if exchange did - // not confirm reserve creation yet. - exchange_initial_amount: Amount; - - // Amount picked up so far. - pickup_amount: Amount; - - // Amount approved for rewards that exceeds the pickup_amount. - committed_amount: Amount; - - // Is this reserve active (false if it was deleted but not purged)? - active: boolean; - } - - -Query funds remaining ---------------------- - -.. http:get:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB - - Obtain information about a specific reserve that have been created for rewards. - - **Request:** - - :query rewards: *Optional*. If set to "yes", returns also information about all of the rewards created. - - **Response:** - - :http:statuscode:`200 OK`: - Returns the `ReserveDetail`. - :http:statuscode:`404 Not found`: - The reward reserve is not known. - :http:statuscode:`502 Bad gateway`: - We are having trouble with the request because of a problem with the exchange. - Likely returned with an "exchange_code" in addition to a "code" and - an "exchange_http_status" in addition to our own HTTP status. Also usually - includes the full exchange reply to our request under "exchange_reply". - This is only returned if there was actual trouble with the exchange, not - if the exchange merely did not respond yet or if it responded that the - reserve was not yet filled. - :http:statuscode:`504 Gateway timeout`: - The merchant's interaction with the exchange took too long. - The client might want to try again later. - - .. ts:def:: ReserveDetail - - interface ReserveDetail { - // Timestamp when it was established. - creation_time: Timestamp; - - // Timestamp when it expires. - expiration_time: Timestamp; - - // Initial amount as per reserve creation call. - merchant_initial_amount: Amount; - - // Initial amount as per exchange, 0 if exchange did - // not confirm reserve creation yet. - exchange_initial_amount: Amount; - - // Amount picked up so far. - pickup_amount: Amount; - - // Amount approved for rewards that exceeds the pickup_amount. - committed_amount: Amount; - - // Array of all rewards created by this reserves (possibly empty!). - // Only present if asked for explicitly. - rewards?: RewardStatusEntry[]; - - // Is this reserve active (false if it was deleted but not purged)? - active: boolean; - - // Array of wire accounts of the exchange that could - // be used to fill the reserve, can be NULL - // if the reserve is inactive or was already filled - accounts?: WireAccount[]; - - // URL of the exchange hosting the reserve, - // NULL if the reserve is inactive - exchange_url: string; - } - - .. ts:def:: RewardStatusEntry - - interface RewardStatusEntry { - - // Unique identifier for the reward. - reward_id: HashCode; - - // Total amount of the reward that can be withdrawn. - total_amount: Amount; - - // Human-readable reason for why the reward was granted. - reason: string; - } - - -Authorizing rewards -------------------- - -.. note:: - - This API is deprecated as of protocol v8. - -.. http:post:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB/authorize-reward - - Authorize creation of a reward from the given reserve. - - **Request:** - - The request body is a `RewardCreateRequest` object. - - **Response:** - - :http:statuscode:`200 OK`: - A reward has been created. The backend responds with a `RewardCreateConfirmation`. - :http:statuscode:`404 Not found`: - The instance or the reserve is unknown to the backend. - :http:statuscode:`412 Precondition failed`: - The reward amount requested exceeds the available reserve balance for rewards. - - .. ts:def:: RewardCreateRequest - - interface RewardCreateRequest { - // Amount that the customer should be rewarded. - amount: Amount; - - // Justification for giving the reward. - justification: string; - - // URL that the user should be directed to after receiving the reward, - // will be included in the reward_token. - next_url: string; - } - - .. ts:def:: RewardCreateConfirmation - - interface RewardCreateConfirmation { - // Unique reward identifier for the reward that was created. - reward_id: HashCode; - - // taler://reward URI for the reward. - taler_reward_uri: string; - - // URL that will directly trigger processing - // the reward when the browser is redirected to it. - reward_status_url: string; - - // When does the reward expire? - reward_expiration: Timestamp; - } - - -.. http:post:: [/instances/$INSTANCE]/private/rewards - - Authorize creation of a reward, with - automatic selection of a working reserve of the instance by the - backend. Intentionally otherwise identical to the ``/authorize-reward`` - endpoint given above. - - **Request:** - - The request body is a `RewardCreateRequest` object. - - **Response:** - - :http:statuscode:`200 OK`: - A reward has been created. The backend responds with a `RewardCreateConfirmation`. - :http:statuscode:`404 Not found`: - The instance is unknown to the backend. - :http:statuscode:`412 Precondition failed`: - The reward amount requested exceeds the available reserve balance for rewards - in all of the reserves of the instance. - - -Deleting reserves ------------------ - -.. note:: - - This API is deprecated as of protocol v8. - -.. http:delete:: [/instances/$INSTANCE]/private/reserves/$RESERVE_PUB - - Delete information about a reserve. Fails if the reserve still has - committed to rewards that were not yet picked up and that have not yet - expired. - - **Request:** - - :query purge: *Optional*. If set to YES, the reserve and all information - about rewards it issued will be fully deleted. - Otherwise only the private key would be deleted. - - **Response:** - - :http:statuscode:`204 No content`: - The backend has successfully deleted the reserve. - :http:statuscode:`404 Not found`: - The backend does not know the instance or the reserve. - :http:statuscode:`409 Conflict`: - The backend refuses to delete the reserve (committed rewards awaiting pickup). - - -Checking reward status ----------------------- - -.. note:: - - This API is deprecated as of protocol v8. - -.. http:get:: [/instances/$INSTANCE]/private/rewards/$REWARD_ID - - Obtain information about a particular reward. - - **Request:** - - :query pickups: *Optional*. If set to "yes", returns also information about all of the pickups. - :query min_amount: *Optional*. Minimum pick-up amount the client is interested in. - :query timeout_ms=NUMBER: *Optional.* If specified, the merchant backend will - wait up to ``timeout_ms`` milliseconds for rewards of at least min_pick_up to be - picked up. A client must never rely on this behavior, as the - merchant backend may return a response immediately. - - **Response:** - - :http:statuscode:`200 OK`: - The reward is known. The backend responds with a `RewardDetails` message. - :http:statuscode:`404 Not found`: - The reward is unknown to the backend. - - .. ts:def:: RewardDetails - - interface RewardDetails { - // Amount that we authorized for this reward. - total_authorized: Amount; - - // Amount that was picked up by the user already. - total_picked_up: Amount; - - // Human-readable reason given when authorizing the reward. - reason: string; - - // Timestamp indicating when the reward is set to expire (may be in the past). - expiration: Timestamp; - - // Reserve public key from which the reward is funded. - reserve_pub: EddsaPublicKey; - - // Array showing the pickup operations of the wallet (possibly empty!). - // Only present if asked for explicitly. - pickups?: PickupDetail[]; - } - - .. ts:def:: PickupDetail - - interface PickupDetail { - // Unique identifier for the pickup operation. - pickup_id: HashCode; - - // Number of planchets involved. - num_planchets: Integer; - - // Total amount requested for this pickup_id. - requested_amount: Amount; - } - - -.. http:get:: [/instances/$INSTANCE]/private/rewards - - Return the list of all rewards. - - **Request:** - - :query include_expired: *Optional*. If set to "yes", the result includes expired rewards also. Otherwise, only active rewards are returned. - - :query limit: *Optional*. At most return the given number of results. Negative for descending in database row id, positive for ascending in database row id. - - :query offset: *Optional*. Starting ``row_id`` for an iteration. - - **Response:** - - :http:statuscode:`200 OK`: - The backend has successfully found the list of rewards. The backend responds - with a `RewardsResponse`. - - .. ts:def:: RewardsResponse - - interface RewardsResponse { - - // List of rewards that are present in the backend. - rewards: Reward[]; - } - - .. ts:def:: Reward - - interface Reward { - - // ID of the reward in the backend database. - row_id: number; - - // Unique identifier for the reward. - reward_id: HashCode; - - // (Remaining) amount of the reward (including fees). - reward_amount: Amount; - } - ----------- OTP Devices ----------- -- cgit v1.2.3