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 RecoupRefreshConfirmation. 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.

404 Not found:

The denomination key is unknown, or the blinded coin is not known to have been withdrawn. If the denomination key is unknown, the response will be a DenominationUnknownMessage.

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 not yet or no longer valid. It either before the validity start, 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.

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 RecoupRefreshConfirmation {
  // Public key of the old coin that will receive the recoup.
  old_coin_pub: EddsaPublicKey;

  // The new balance of the old coin, after it has absorved
  // the residual values of the coins from the request.
  balance: Amount;
}