taler-docs

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

post-recoup-refresh.rst (4372B)

      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
     26     is a `RecoupRefreshConfirmationResponse`.
     27     Note that repeating exactly the same request
     28     will again yield the same response, so if the
     29     network goes down during the transaction or
     30     before the client can commit the coin signature to disk,
     31     the coin is not lost.
     32   :http:statuscode:`403 Forbidden`:
     33     The coin's signature is invalid.
     34     This response comes with a standard `ErrorDetail` response.
     35     Possible error codes include
     36     ``TALER_EC_EXCHANGE_RECOUP_REFRESH_SIGNATURE_INVALID`` or
     37     ``TALER_EC_EXCHANGE_DENOMINATION_SIGNATURE_INVALID``.
     38   :http:statuscode:`404 Not found`:
     39     The denomination key is unknown, the blinded
     40     coin is not known to have been withdrawn,
     41     or the denomination is not eligible for recoup.
     42     If the denomination key is unknown, the response will be
     43     a `DenominationUnknownMessage`.
     44     Possible error codes include
     45     ``TALER_EC_EXCHANGE_RECOUP_REFRESH_MELT_NOT_FOUND`` or
     46     ``TALER_EC_EXCHANGE_RECOUP_REFRESH_NOT_ELIGIBLE``.
     47   :http:statuscode:`409 Conflict`:
     48     The operation is not allowed as the coin has insufficient
     49     residual value, or because the same public key of the coin has been
     50     previously used with a different denomination.  Which case it is
     51     can be decided by looking at the error code
     52     (usually ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_BALANCE``).
     53     The response is a `DepositDoubleSpendError`.
     54   :http:statuscode:`410 Gone`:
     55     The requested denomination key is no longer valid.
     56     It is past the expiration or was not yet revoked. The response is a
     57     `DenominationGoneMessage`. Clients must evaluate
     58     the error code provided to understand which of the
     59     cases this is and handle it accordingly.
     60     Possible error codes include
     61     ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED``.
     62   :http:statuscode:`412 Precondition Failed`:
     63     The requested denomination key is not yet valid.
     64     It is before the validity start time. The response is a
     65     `DenominationGoneMessage` with
     66     ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE``.
     67   :http:statuscode:`413 Request entity too large`:
     68     The uploaded body is to long, it exceeds the size limit.
     69     Returned with an error code of
     70     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     71   :http:statuscode:`500 Internal Server Error`:
     72     The exchange encountered an internal error.
     73     This response comes with a standard `ErrorDetail` response.
     74     Possible error codes include
     75     ``TALER_EC_EXCHANGE_RECOUP_REFRESH_BLINDING_FAILED``,
     76     ``TALER_EC_GENERIC_DB_FETCH_FAILED``, or
     77     ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``.
     78 
     79   **Details:**
     80 
     81   .. ts:def:: RecoupRefreshRequest
     82 
     83     interface RecoupRefreshRequest {
     84       // Public key of the original coin that will receive the recoup.
     85       // MUST be the same as the one from the original refresh request.
     86       old_coin_pub: EddsaPublicKey;
     87 
     88       // The details about the coins:
     89       // An array of either
     90       // a) the hash code of a blinded coin envelope (not to be recouped)
     91       // b) the disclosed coin details, in order to recoup it.
     92       // From these, the hash of all coin envelopes
     93       // from the original refresh can be reconstructed.
     94       coin_data: RecoupCoinData[];
     95     }
     96 
     97 
     98   .. ts:def:: RecoupRefreshConfirmationResponse
     99 
    100     interface RecoupRefreshConfirmationResponse {
    101       // Public key of the old coin that will receive the recoup.
    102       old_coin_pub: EddsaPublicKey;
    103 
    104     }