POST /recoup-refresh

Demand that a batch of coins be refunded to the original coin, from which the coins were originally refreshed. The coins must have been originated from the same call to refresh, and be a subset of that original batch. The remaining amount on the coin will be credited to the original coin that the coins were refreshed from, in the same refresh request.

The base URL for coin related requests may differ from the main base URL of the exchange. The exchange MUST return a 307 or 308 redirection to the correct base URL if this is the case.

Note that the original refresh fees will not be recouped.

Note

This endpoint still Work-in-Progress. It will be implemented in vRECOUP, sometime after v32.

Request:

The request body must be a RecoupRefreshRequest object.

Response:

200 OK:

The request was successful, and the response is a RecoupRefreshConfirmationResponse. Note that repeating exactly the same request will again yield the same response, so if the network goes down during the transaction or before the client can commit the coin signature to disk, the coin is not lost.

403 Forbidden:

The coin’s signature is invalid. This response comes with a standard ErrorDetail response. Possible error codes include TALER_EC_EXCHANGE_RECOUP_REFRESH_SIGNATURE_INVALID or TALER_EC_EXCHANGE_DENOMINATION_SIGNATURE_INVALID.

404 Not found:

The denomination key is unknown, the blinded coin is not known to have been withdrawn, or the denomination is not eligible for recoup. If the denomination key is unknown, the response will be a DenominationUnknownMessage. Possible error codes include TALER_EC_EXCHANGE_RECOUP_REFRESH_MELT_NOT_FOUND or TALER_EC_EXCHANGE_RECOUP_REFRESH_NOT_ELIGIBLE.

409 Conflict:

The operation is not allowed as the coin has insufficient residual value, or because the same public key of the coin has been previously used with a different denomination. Which case it is can be decided by looking at the error code (usually TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_BALANCE). The response is a DepositDoubleSpendError.

410 Gone:

The requested denomination key is no longer valid. It is past the expiration or was not yet revoked. The response is a DenominationGoneMessage. Clients must evaluate the error code provided to understand which of the cases this is and handle it accordingly. Possible error codes include TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED.

412 Precondition Failed:

The requested denomination key is not yet valid. It is before the validity start time. The response is a DenominationGoneMessage with TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE.

413 Request entity too large:

The uploaded body is to long, it exceeds the size limit. Returned with an error code of TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT.

500 Internal Server Error:

The exchange encountered an internal error. This response comes with a standard ErrorDetail response. Possible error codes include TALER_EC_EXCHANGE_RECOUP_REFRESH_BLINDING_FAILED, TALER_EC_GENERIC_DB_FETCH_FAILED, or TALER_EC_GENERIC_DB_INVARIANT_FAILURE.

Details:

interface RecoupRefreshRequest {
  // Public key of the original coin that will receive the recoup.
  // MUST be the same as the one from the original refresh request.
  old_coin_pub: EddsaPublicKey;

  // The details about the coins:
  // An array of either
  // a) the hash code of a blinded coin envelope (not to be recouped)
  // b) the disclosed coin details, in order to recoup it.
  // From these, the hash of all coin envelopes
  // from the original refresh can be reconstructed.
  coin_data: RecoupCoinData[];
}

interface RecoupRefreshConfirmationResponse {
  // Public key of the old coin that will receive the recoup.
  old_coin_pub: EddsaPublicKey;

}