taler-docs

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

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

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