taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

post-coins-COIN_PUB-refund.rst (4678B)

      1 .. http:post:: /coins/$COIN_PUB/refund
      2 
      3   Undo deposit of the given coin, restoring its value.
      4 
      5   **Request:**
      6 
      7   The request body must be a `RefundRequest` object.
      8 
      9   **Response:**
     10 
     11   :http:statuscode:`200 OK`:
     12     The operation succeeded, the exchange confirms that the coin can now be refreshed.  The response will include a `RefundSuccess` object.
     13   :http:statuscode:`400 Bad Request`:
     14     The request is somehow not following the protocol.
     15     Returned with error codes of:
     16     - ``TALER_EC_EXCHANGE_REFUND_FEE_TOO_LOW``
     17     - ``TALER_EC_EXCHANGE_REFUND_FEE_ABOVE_AMOUNT``
     18 
     19   :http:statuscode:`403 Forbidden`:
     20     Merchant signature is invalid.
     21     This response comes with a standard `ErrorDetail` response.
     22     Returned with an error code of
     23     ``TALER_EC_EXCHANGE_REFUND_MERCHANT_SIGNATURE_INVALID``.
     24   :http:statuscode:`404 Not Found`:
     25     The refund operation failed as we could not find a matching deposit operation (coin, contract, transaction ID and merchant public key must all match).
     26     This response comes with a standard `ErrorDetail` response.
     27     Returned with an error code of:
     28 
     29     - ``TALER_EC_EXCHANGE_REFUND_DEPOSIT_NOT_FOUND`` or
     30     - ``TALER_EC_EXCHANGE_REFUND_COIN_NOT_FOUND``
     31 
     32   :http:statuscode:`409 Conflict`:
     33     This response comes with a standard `ErrorDetail` response.
     34     There are several possible error codes:
     35 
     36     - ``TALER_EC_EXCHANGE_REFUND_CONFLICT_DEPOSIT_INSUFFICIENT``:
     37       The requested amount for the refund exceeds the deposit value.
     38     - ``TALER_EC_EXCHANGE_REFUND_INCONSISTENT_AMOUNT``:
     39       The exchange has previously received a refund request for the same
     40       coin, merchant and contract, but specifying a different amount for
     41       the same refund transaction ID.
     42 
     43   :http:statuscode:`410 Gone`:
     44     It is too late for a refund by the exchange, the money was already sent to the merchant.
     45     This response comes with a standard `ErrorDetail` response.
     46     Returned with an error code of
     47     ``TALER_EC_EXCHANGE_REFUND_MERCHANT_ALREADY_PAID``.
     48   :http:statuscode:`413 Request Entity Too Large`:
     49     The uploaded body is to long, it exceeds the size limit.
     50     Returned with an error code of
     51     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     52   :http:statuscode:`424 Failed Dependency`:
     53     The request transaction ID is identical to a previous refund request by the same
     54     merchant for the same coin and contract, but the refund amount differs. (The
     55     failed dependency is that the ``rtransaction_id`` is not unique.)
     56     Returned with an error code of:
     57     - ``TALER_EC_EXCHANGE_REFUND_INCONSISTENT_AMOUNT``
     58     FIXME: consider turning this into a 409 in the future.
     59   :http:statuscode:`500 Internal Server Error`:
     60     The server encountered an internal error processing the request.
     61     Returned with error codes of:
     62 
     63     - ``TALER_EC_EXCHANGE_REFUND_MERCHANT_SIGNING_FAILED``
     64     - ``TALER_EC_GENERIC_DB_STORE_FAILED``
     65     - ``TALER_EC_GENERIC_DB_FETCH_FAILED``
     66 
     67   **Details:**
     68 
     69   The deposit fee is waived only when the cumulative refunds for this
     70   particular coin return its full deposited contribution.  A partial refund,
     71   or a full refund of an order that leaves this coin only partially refunded,
     72   does not waive the coin's deposit fee.
     73 
     74   .. ts:def:: RefundRequest
     75 
     76      interface RefundRequest {
     77 
     78       // Amount to be refunded, can be a fraction of the
     79       // coin's total deposit value (including deposit fee);
     80       // must be larger than the refund fee.
     81       refund_amount: Amount;
     82 
     83       // SHA-512 hash of the contact of the merchant with the customer.
     84       h_contract_terms: HashCode;
     85 
     86       // 64-bit transaction id of the refund transaction between merchant and customer.
     87       rtransaction_id: Integer;
     88 
     89       // EdDSA public key of the merchant.
     90       merchant_pub: EddsaPublicKey;
     91 
     92       // EdDSA signature of the merchant over a
     93       // `TALER_RefundRequestPS` with purpose
     94       // ``TALER_SIGNATURE_MERCHANT_REFUND``
     95       // affirming the refund.
     96       merchant_sig: EddsaSignature;
     97 
     98     }
     99 
    100   .. ts:def:: RefundSuccess
    101 
    102     interface RefundSuccess {
    103 
    104       // The EdDSA :ref:`signature` (binary-only) with purpose
    105       // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND`` over
    106       // a `TALER_RecoupRefreshConfirmationPS`
    107       // using a current signing key of the
    108       // exchange affirming the successful refund.
    109       exchange_sig: EddsaSignature;
    110 
    111       // Public EdDSA key of the exchange that was used to generate the signature.
    112       // Should match one of the exchange's signing keys from ``/keys``.  It is given
    113       // explicitly as the client might otherwise be confused by clock skew as to
    114       // which signing key was used.
    115       exchange_pub: EddsaPublicKey;
    116    }