taler-docs

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

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

      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   :http:statuscode:`403 Forbidden`:
     19     Merchant signature is invalid.
     20     This response comes with a standard `ErrorDetail` response.
     21     Returned with an error code of
     22     ``TALER_EC_EXCHANGE_REFUND_MERCHANT_SIGNATURE_INVALID``.
     23   :http:statuscode:`404 Not found`:
     24     The refund operation failed as we could not find a matching deposit operation (coin, contract, transaction ID and merchant public key must all match).
     25     This response comes with a standard `ErrorDetail` response.
     26     Returned with an error code of
     27     - ``TALER_EC_EXCHANGE_REFUND_DEPOSIT_NOT_FOUND`` or
     28     - ``TALER_EC_EXCHANGE_REFUND_COIN_NOT_FOUND``
     29   :http:statuscode:`409 Conflict`:
     30     This response comes with a standard `ErrorDetail` response.
     31     There are several possible error codes:
     32     - ``TALER_EC_EXCHANGE_REFUND_CONFLICT_DEPOSIT_INSUFFICIENT``:
     33       The requested amount for the refund exceeds the deposit value.
     34     -
     35     The exchange has previously received a refund request for the same coin,
     36     merchant and contract, but specifying a different amount for the same
     37     refund transaction ID.
     38   :http:statuscode:`410 Gone`:
     39     It is too late for a refund by the exchange, the money was already sent to the merchant.
     40     This response comes with a standard `ErrorDetail` response.
     41     Returned with an error code of
     42     ``TALER_EC_EXCHANGE_REFUND_MERCHANT_ALREADY_PAID``.
     43   :http:statuscode:`413 Request entity too large`:
     44     The uploaded body is to long, it exceeds the size limit.
     45     Returned with an error code of
     46     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     47   :http:statuscode:`424 Failed dependency`:
     48     The request transaction ID is identical to a previous refund request by the same
     49     merchant for the same coin and contract, but the refund amount differs. (The
     50     failed dependency is that the ``rtransaction_id`` is not unique.)
     51     Returned with an error code of:
     52     - ``TALER_EC_EXCHANGE_REFUND_INCONSISTENT_AMOUNT``
     53     FIXME: consider turning this into a 409 in the future.
     54   :http:statuscode:`500 Internal server error`:
     55     The server encountered an internal error processing the request.
     56     Returned with error codes of:
     57     - ``TALER_EC_EXCHANGE_REFUND_MERCHANT_SIGNING_FAILED``
     58     - ``TALER_EC_GENERIC_DB_STORE_FAILED``
     59     - ``TALER_EC_GENERIC_DB_FETCH_FAILED``
     60 
     61   **Details:**
     62 
     63   .. ts:def:: RefundRequest
     64 
     65      interface RefundRequest {
     66 
     67       // Amount to be refunded, can be a fraction of the
     68       // coin's total deposit value (including deposit fee);
     69       // must be larger than the refund fee.
     70       refund_amount: Amount;
     71 
     72       // SHA-512 hash of the contact of the merchant with the customer.
     73       h_contract_terms: HashCode;
     74 
     75       // 64-bit transaction id of the refund transaction between merchant and customer.
     76       rtransaction_id: Integer;
     77 
     78       // EdDSA public key of the merchant.
     79       merchant_pub: EddsaPublicKey;
     80 
     81       // EdDSA signature of the merchant over a
     82       // `TALER_RefundRequestPS` with purpose
     83       // ``TALER_SIGNATURE_MERCHANT_REFUND``
     84       // affirming the refund.
     85       merchant_sig: EddsaSignature;
     86 
     87     }
     88 
     89   .. ts:def:: RefundSuccess
     90 
     91     interface RefundSuccess {
     92 
     93       // The EdDSA :ref:`signature` (binary-only) with purpose
     94       // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND`` over
     95       // a `TALER_RecoupRefreshConfirmationPS`
     96       // using a current signing key of the
     97       // exchange affirming the successful refund.
     98       exchange_sig: EddsaSignature;
     99 
    100       // Public EdDSA key of the exchange that was used to generate the signature.
    101       // Should match one of the exchange's signing keys from ``/keys``.  It is given
    102       // explicitly as the client might otherwise be confused by clock skew as to
    103       // which signing key was used.
    104       exchange_pub: EddsaPublicKey;
    105    }