taler-docs

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

post-private-orders-ORDER_ID-refund.rst (2151B)

      1 .. http:post:: [/instances/$INSTANCE]/private/orders/$ORDER_ID/refund
      2 
      3   Increase the refund amount associated with a given order.  The user should be
      4   redirected to the ``taler_refund_uri`` to trigger refund processing in the wallet.
      5 
      6   **Required permission:** ``orders-refund``
      7 
      8   **Request:**
      9 
     10   The request body is a `RefundRequest` object.
     11 
     12   **Response:**
     13 
     14   :http:statuscode:`200 OK`:
     15     The refund amount has been increased, the backend
     16     responds with a `MerchantRefundResponse`.
     17   :http:statuscode:`400 Bad Request`:
     18     The request body is malformed.
     19   :http:statuscode:`403 Forbidden`:
     20     For the given order, the refund delay was zero and thus
     21     refunds are categorically not allowed.
     22   :http:statuscode:`404 Not found`:
     23     The order is unknown to the merchant.
     24   :http:statuscode:`410 Gone`:
     25     It is too late for aborting, the exchange may have already wired the funds
     26     to the merchant.
     27   :http:statuscode:`409 Conflict`:
     28     The refund amount exceeds the amount originally paid.
     29   :http:statuscode:`451 Unavailable for Legal Reasons`:
     30     The refund could not be awarded because of legal
     31     reasons (an exchange would refuse). The merchant
     32     staff needs to find another way to give a refund
     33     to the customer.
     34     The body is an `ErrorDetail` with an error
     35     code of ``MERCHANT_POST_ORDERS_ID_REFUND_EXCHANGE_TRANSACTION_LIMIT_VIOLATION``.
     36   :http:statuscode:`500 Internal Server Error`:
     37     The server experienced an internal failure.
     38     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
     39 
     40   **Details:**
     41 
     42   .. ts:def:: RefundRequest
     43 
     44     interface RefundRequest {
     45       // Amount to be refunded.
     46       refund: Amount;
     47 
     48       // Human-readable refund justification.
     49       reason: string;
     50     }
     51 
     52   .. ts:def:: MerchantRefundResponse
     53 
     54     interface MerchantRefundResponse {
     55 
     56       // URL (handled by the backend) that the wallet should access to
     57       // trigger refund processing.
     58       // taler://refund/...
     59       taler_refund_uri: string;
     60 
     61       // Contract hash that a client may need to authenticate an
     62       // HTTP request to obtain the above URI in a wallet-friendly way.
     63       h_contract: HashCode;
     64     }