taler-docs

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

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

      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 **v42**. For orders with refunds settled through external payment
      7   methods, the cumulative Taler refund must not exceed the full order total
      8   minus those 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 **v42**), or
     33     the order was 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``
     37     (since **v42**).
     38   :http:statuscode:`410 Gone`:
     39     It is too late for refunds, the exchange may have already wired the funds
     40     to the merchant.
     41     Returned with ``TALER_EC_MERCHANT_PRIVATE_POST_REFUND_AFTER_WIRE_DEADLINE``.
     42   :http:statuscode:`451 Unavailable for Legal Reasons`:
     43     The refund could not be awarded because of legal
     44     reasons (an exchange would refuse). The merchant
     45     staff needs to find another way to give a refund
     46     to the customer.
     47     The body is an `ErrorDetail` with an error
     48     code of ``TALER_EC_MERCHANT_POST_ORDERS_ID_REFUND_EXCHANGE_TRANSACTION_LIMIT_VIOLATION``.
     49   :http:statuscode:`500 Internal Server Error`:
     50     The server experienced an internal failure.
     51     Returned with ``TALER_EC_GENERIC_DB_START_FAILED``,
     52     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     53     ``TALER_EC_GENERIC_DB_COMMIT_FAILED``,
     54     ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``,
     55     ``TALER_EC_GENERIC_FAILED_COMPUTE_JSON_HASH`` or
     56     ``TALER_EC_MERCHANT_GENERIC_DB_CONTRACT_CONTENT_INVALID``.
     57 
     58   **Details:**
     59 
     60   .. ts:def:: RefundRequest
     61 
     62     interface RefundRequest {
     63       // Amount to be refunded.
     64       refund: Amount;
     65 
     66       // Human-readable refund justification.
     67       reason: string;
     68     }
     69 
     70   .. ts:def:: MerchantRefundResponse
     71 
     72     interface MerchantRefundResponse {
     73 
     74       // URL (handled by the backend) that the wallet should access to
     75       // trigger refund processing.
     76       // taler://refund/...
     77       taler_refund_uri: string;
     78 
     79       // Contract hash that a client may need to authenticate an
     80       // HTTP request to obtain the above URI in a wallet-friendly way.
     81       h_contract: HashCode;
     82     }