POST /coins/$COIN_PUB/refund

Undo deposit of the given coin, restoring its value.

Request:

The request body must be a RefundRequest object.

Response:

200 OK:

The operation succeeded, the exchange confirms that the coin can now be refreshed. The response will include a RefundSuccess object.

403 Forbidden:

Merchant signature is invalid. This response comes with a standard ErrorDetail response.

404 Not found:

The refund operation failed as we could not find a matching deposit operation (coin, contract, transaction ID and merchant public key must all match). This response comes with a standard ErrorDetail response.

409 Conflict:

The exchange has previously received a refund request for the same coin, merchant and contract, but specifying a different amount for the same refund transaction ID. The response will be a RefundFailure object.

410 Gone:

It is too late for a refund by the exchange, the money was already sent to the merchant. This response comes with a standard ErrorDetail response.

412 Precondition failed:

The request transaction ID is identical to a previous refund request by the same merchant for the same coin and contract, but the refund amount differs. (The failed precondition is that the rtransaction_id is not unique.) The response will be a RefundFailure object with the conflicting refund request.

Details:

 interface RefundRequest {

  // Amount to be refunded, can be a fraction of the
  // coin's total deposit value (including deposit fee);
  // must be larger than the refund fee.
  refund_amount: Amount;

  // SHA-512 hash of the contact of the merchant with the customer.
  h_contract_terms: HashCode;

  // 64-bit transaction id of the refund transaction between merchant and customer.
  rtransaction_id: Integer;

  // EdDSA public key of the merchant.
  merchant_pub: EddsaPublicKey;

  // EdDSA signature of the merchant over a
  // TALER_RefundRequestPS with purpose
  // TALER_SIGNATURE_MERCHANT_REFUND
  // affirming the refund.
  merchant_sig: EddsaPublicKey;

}

 interface RefundSuccess {

   // The EdDSA :ref:signature (binary-only) with purpose
   // TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND over
   // a TALER_RecoupRefreshConfirmationPS
   // using a current signing key of the
   // exchange affirming the successful refund.
   exchange_sig: EddsaSignature;

   // Public EdDSA key of the exchange that was used to generate the signature.
   // Should match one of the exchange's signing keys from /keys.  It is given
   // explicitly as the client might otherwise be confused by clock skew as to
   // which signing key was used.
   exchange_pub: EddsaPublicKey;
}

interface RefundFailure {

  // Numeric error code unique to the condition, which can be either
  // related to the deposit value being insufficient for the requested
  // refund(s), or the requested refund conflicting due to refund
  // transaction number re-use (with different amounts).
  code: Integer;

  // Human-readable description of the error message.
  hint: string;

  // Information about the conflicting refund request(s).
  // This will not be the full history of the coin, but only
  // the relevant subset of the transactions.
  history: CoinSpendHistoryItem[];
}