taler-docs

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

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

      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   .. ts:def:: RefundRequest
     70 
     71      interface RefundRequest {
     72 
     73       // Amount to be refunded, can be a fraction of the
     74       // coin's total deposit value (including deposit fee);
     75       // must be larger than the refund fee.
     76       refund_amount: Amount;
     77 
     78       // SHA-512 hash of the contact of the merchant with the customer.
     79       h_contract_terms: HashCode;
     80 
     81       // 64-bit transaction id of the refund transaction between merchant and customer.
     82       rtransaction_id: Integer;
     83 
     84       // EdDSA public key of the merchant.
     85       merchant_pub: EddsaPublicKey;
     86 
     87       // EdDSA signature of the merchant over a
     88       // `TALER_RefundRequestPS` with purpose
     89       // ``TALER_SIGNATURE_MERCHANT_REFUND``
     90       // affirming the refund.
     91       merchant_sig: EddsaSignature;
     92 
     93     }
     94 
     95   .. ts:def:: RefundSuccess
     96 
     97     interface RefundSuccess {
     98 
     99       // The EdDSA :ref:`signature` (binary-only) with purpose
    100       // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND`` over
    101       // a `TALER_RecoupRefreshConfirmationPS`
    102       // using a current signing key of the
    103       // exchange affirming the successful refund.
    104       exchange_sig: EddsaSignature;
    105 
    106       // Public EdDSA key of the exchange that was used to generate the signature.
    107       // Should match one of the exchange's signing keys from ``/keys``.  It is given
    108       // explicitly as the client might otherwise be confused by clock skew as to
    109       // which signing key was used.
    110       exchange_pub: EddsaPublicKey;
    111    }