taler-docs

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

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

      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   Since ``vMixedPayments``. For orders with refunds settled through external payment methods,
      7   the cumulative Taler refund must not exceed the full order total minus those
      8   external refunds.
      9 
     10   **Required permission:** ``orders-refund`` (see :ref:`Scopes <merchant-api-scopes>`)
     11 
     12   **Request:**
     13 
     14   The request body is a `RefundRequest` object.
     15 
     16   **Response:**
     17 
     18   :http:statuscode:`200 OK`:
     19     The refund amount has been increased, the backend
     20     responds with a `MerchantRefundResponse`.
     21   :http:statuscode:`400 Bad Request`:
     22     The request body is malformed.
     23   :http:statuscode:`403 Forbidden`:
     24     For the given order, the refund delay was zero and thus
     25     refunds are categorically not allowed.
     26     Returned with ``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_REFUND_NOT_ALLOWED_BY_CONTRACT``.
     27   :http:statuscode:`404 Not found`:
     28     The order is unknown to the merchant.
     29     Returned with ``TALER_EC_MERCHANT_GENERIC_ORDER_UNKNOWN``.
     30   :http:statuscode:`409 Conflict`:
     31     The refund amount exceeds the amount originally paid, the combined Taler
     32     and external refunds would exceed the full order total (since ``vMixedPayments``), or the order was
     33     not yet paid.
     34     Returned with ``TALER_EC_MERCHANT_GENERIC_CURRENCY_MISMATCH`` or
     35     ``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_REFUND_ORDER_UNPAID``,
     36     ``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_REFUND_INCONSISTENT_AMOUNT`` (since ``vMixedPayments``).
     37   :http:statuscode:`410 Gone`:
     38     It is too late for refunds, the exchange may have already wired the funds
     39     to the merchant.
     40     Returned with ``TALER_EC_MERCHANT_PRIVATE_POST_REFUND_AFTER_WIRE_DEADLINE``.
     41   :http:statuscode:`451 Unavailable for Legal Reasons`:
     42     The refund could not be awarded because of legal
     43     reasons (an exchange would refuse). The merchant
     44     staff needs to find another way to give a refund
     45     to the customer.
     46     The body is an `ErrorDetail` with an error
     47     code of ``TALER_EC_MERCHANT_POST_ORDERS_ID_REFUND_EXCHANGE_TRANSACTION_LIMIT_VIOLATION``.
     48   :http:statuscode:`500 Internal Server Error`:
     49     The server experienced an internal failure.
     50     Returned with ``TALER_EC_GENERIC_DB_START_FAILED``,
     51     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     52     ``TALER_EC_GENERIC_DB_COMMIT_FAILED``,
     53     ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``,
     54     ``TALER_EC_GENERIC_FAILED_COMPUTE_JSON_HASH`` or
     55     ``TALER_EC_MERCHANT_GENERIC_DB_CONTRACT_CONTENT_INVALID``.
     56 
     57   **Details:**
     58 
     59   .. ts:def:: RefundRequest
     60 
     61     interface RefundRequest {
     62       // Amount to be refunded.
     63       refund: Amount;
     64 
     65       // Human-readable refund justification.
     66       reason: string;
     67     }
     68 
     69   .. ts:def:: MerchantRefundResponse
     70 
     71     interface MerchantRefundResponse {
     72 
     73       // URL (handled by the backend) that the wallet should access to
     74       // trigger refund processing.
     75       // taler://refund/...
     76       taler_refund_uri: string;
     77 
     78       // Contract hash that a client may need to authenticate an
     79       // HTTP request to obtain the above URI in a wallet-friendly way.
     80       h_contract: HashCode;
     81     }