taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

post-recoup-refresh.rst (3293B)

      1 .. http:post:: /recoup-refresh
      2 
      3   Demand that a batch of coins be refunded to the original coin,
      4   from which the coins were originally refreshed.
      5   The coins must have been originated from the same call to refresh, and be
      6   a subset of that original batch.
      7   The remaining amount on the coin will be credited to the original coin
      8   that the coins were refreshed from, in the same refresh request.
      9 
     10   The base URL for coin related requests may differ from the main base URL of the
     11   exchange. The exchange MUST return a 307 or 308 redirection to the correct
     12   base URL if this is the case.
     13 
     14   Note that the original refresh fees will **not** be recouped.
     15 
     16   .. note:: This endpoint still Work-in-Progress.  It will be implemented in **vRECOUP**, sometime after **v32**.
     17 
     18   **Request:**
     19 
     20   The request body must be a `RecoupRefreshRequest` object.
     21 
     22   **Response:**
     23 
     24   :http:statuscode:`200 OK`:
     25     The request was successful, and the response is a `RecoupRefreshConfirmation`.
     26     Note that repeating exactly the same request
     27     will again yield the same response, so if the network goes down during the
     28     transaction or before the client can commit the coin signature to disk, the
     29     coin is not lost.
     30   :http:statuscode:`403 Forbidden`:
     31     The coin's signature is invalid.
     32     This response comes with a standard `ErrorDetail` response.
     33   :http:statuscode:`404 Not found`:
     34     The denomination key is unknown, or the blinded
     35     coin is not known to have been withdrawn.
     36     If the denomination key is unknown, the response will be
     37     a `DenominationUnknownMessage`.
     38   :http:statuscode:`409 Conflict`:
     39     The operation is not allowed as the coin has insufficient
     40     residual value, or because the same public key of the coin has been
     41     previously used with a different denomination.  Which case it is
     42     can be decided by looking at the error code
     43     (usually ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_BALANCE``).
     44     The response is a `DepositDoubleSpendError`.
     45   :http:statuscode:`410 Gone`:
     46     The requested denomination key is not yet or no longer valid.
     47     It either before the validity start, past the expiration or was not yet revoked. The response is a
     48     `DenominationGoneMessage`. Clients must evaluate
     49     the error code provided to understand which of the
     50     cases this is and handle it accordingly.
     51 
     52   **Details:**
     53 
     54   .. ts:def:: RecoupRefreshRequest
     55 
     56     interface RecoupRefreshRequest {
     57       // Public key of the original coin that will receive the recoup.
     58       // MUST be the same as the one from the original refresh request.
     59       old_coin_pub: EddsaPublicKey;
     60 
     61       // The details about the coins:
     62       // An array of either
     63       // a) the hash code of a blinded coin envelope (not to be recouped)
     64       // b) the disclosed coin details, in order to recoup it.
     65       // From these, the hash of all coin envelopes
     66       // from the original refresh can be reconstructed.
     67       coin_data: RecoupCoinData[];
     68     }
     69 
     70 
     71   .. ts:def:: RecoupRefreshConfirmation
     72 
     73     interface RecoupRefreshConfirmation {
     74       // Public key of the old coin that will receive the recoup.
     75       old_coin_pub: EddsaPublicKey;
     76 
     77       // The new balance of the old coin, after it has absorved
     78       // the residual values of the coins from the request.
     79       balance: Amount;
     80     }