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.

400 Bad request:

The request is somehow not following the protocol. Returned with error codes of: - TALER_EC_EXCHANGE_REFUND_FEE_TOO_LOW - TALER_EC_EXCHANGE_REFUND_FEE_ABOVE_AMOUNT

403 Forbidden:

Merchant signature is invalid. This response comes with a standard ErrorDetail response. Returned with an error code of TALER_EC_EXCHANGE_REFUND_MERCHANT_SIGNATURE_INVALID.

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. Returned with an error code of - TALER_EC_EXCHANGE_REFUND_DEPOSIT_NOT_FOUND or - TALER_EC_EXCHANGE_REFUND_COIN_NOT_FOUND

409 Conflict:

This response comes with a standard ErrorDetail response. There are several possible error codes: - TALER_EC_EXCHANGE_REFUND_CONFLICT_DEPOSIT_INSUFFICIENT:

The requested amount for the refund exceeds the deposit value.

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.

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. Returned with an error code of TALER_EC_EXCHANGE_REFUND_MERCHANT_ALREADY_PAID.

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.

424 Failed dependency:

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 dependency is that the rtransaction_id is not unique.) Returned with an error code of: - TALER_EC_EXCHANGE_REFUND_INCONSISTENT_AMOUNT FIXME: consider turning this into a 409 in the future.

500 Internal server error:

The server encountered an internal error processing the request. Returned with error codes of: - TALER_EC_EXCHANGE_REFUND_MERCHANT_SIGNING_FAILED - TALER_EC_GENERIC_DB_STORE_FAILED - TALER_EC_GENERIC_DB_FETCH_FAILED

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: EddsaSignature;

}

 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;
}