POST /recoup-withdraw

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

Note that the original withdrawal 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 RecoupWithdrawRequest object.

It provides sufficient information to a) identify the originating withdraw request b) proof that the coins to be recouped were part of that withdraw request c) proof ownership of all coins requested to be recouped.

Response:

200 OK:

The request was successful, and the response is a ReserveSummary.

403 Forbidden:

A coin’s signature is invalid. This response comes with a standard ErrorDetail response.

404 Not found:

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

409 Conflict:

The operation is not allowed as a coin has insufficient residual value, or because the same public key of a 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_FUNDS). The response is a DepositDoubleSpendError.

410 Gone:

A 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 RecoupWithdrawRequest {
  // Public key of the reserve that will receive the recoup.
  // MUST be the same as the one from the original withdraw.
  reserve_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 withdraw can be reconstructed.
  coin_data: RecoupCoinData[];
}

// This is either
// a) the hash code of a blinded coin envelope (not to be recouped)
// b) the disclosed coin details, in order to recoup it.
type RecoupCoinData =
   | NonRecoupedCoin
   | RecoupDisclosedCoinDetails;

interface  NonRecoupedCoin {
  type: "non_recouped_coin";

  // This is the SHA512 hash code of a blinded coin envelope,
  // including the corresponding denomination's hash.
  // It is the output of the TALER_coin_ev_hash function
  // from libtalerutil.
  coin_ev: BlindedCoinEnvelopeHash;
};

// The hash value of a blinded coin envelope,
// as it its generated by the function TALER_coin_ev_hash
// in libtalerutil.
type BlindedCoinEnvelopeHash = HashCode;

// This object provides all necessary coin data
// in order to call TALER_denom_blind and retrieve
// a blinded coin planchet, from which we can
// calculate the blinded coin envelope hash.
// It also contains the denomination's signature
// for the (unblinded) coin's public key,
// and the coin's signature to authorize the recoup request.
interface RecoupDisclosedCoinDetails {
  type: "recoup_coin_details";

  // The coin's public key
  coin_pub: CoinPublicKey;

  // The blinding secret for this coin
  // that was used during withdraw
  coin_blinding_key_secret: DenominationBlindingKeySecret;

  // The coin's commitment for age restriction,
  // if the denomination had age restriction support.
  age_commitment_h?: AgeCommitmentHash;

  // The blinding nonce that went into this coin's
  // blinded envelope
  cs_session_nonce?: HashCode;

  // In case of Clause-Schnorr denomination,
  // the blinding values that were provided
  // for this coin, by the exchange, as response
  // to a call to /blinding-prepare.
  cs_r_pubs?: CSRPublicPair;

  // Unblinded signature of the coins' public key,
  // signed by the denomination key.
  denom_pub_sig: DenominationSignature;

  // The denomination public key.
  // This denomination MUST be eligible for recoup,
  // i.e. being listed in the "recoup" section of /config.
  denom_pub_h: HashCode;

  // Signature of TALER_RecoupRequestPS,
  // created by this coin's private key.
  coin_sig: EddsaSignature;
}