taler-docs

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

post-orders-ORDER_ID-refund.rst (4579B)

      1 .. http:post:: [/instances/$INSTANCE]/orders/$ORDER_ID/refund
      2 
      3   Obtain refunds for an order. After talking to the exchange, the refunds will
      4   no longer be pending if processed successfully.
      5 
      6   **Request:**
      7 
      8   The request body is a `WalletRefundRequest` object.
      9 
     10   **Response:**
     11 
     12   :http:statuscode:`200 OK`:
     13     The response is a `WalletRefundResponse`.
     14   :http:statuscode:`204 No content`:
     15     There are no refunds possible for the order. Should
     16     mean that the order was paid, but the total was zero,
     17     hence refunds are not possible.
     18   :http:statuscode:`403 Forbidden`:
     19     The ``h_contract`` does not match the order.
     20     Returned with ``TALER_EC_MERCHANT_GENERIC_CONTRACT_HASH_DOES_NOT_MATCH_ORDER``.
     21   :http:statuscode:`404 Not found`:
     22     The merchant backend is unaware of the instance or order.
     23 
     24     Applicable error codes:
     25     * ``MERCHANT_GENERIC_ORDER_UNKNOWN``
     26     * ``MERCHANT_GENERIC_INSTANCE_UNKNOWN``
     27 
     28   :http:statuscode:`410 Gone`:
     29     The wire deadline has past and it is too late to grant a refund.
     30     Since protocol **v24**.
     31   :http:statuscode:`413 Request entity too large`:
     32     The uploaded body is to long, it exceeds the size limit.
     33     Returned with an error code of
     34     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     35   :http:statuscode:`500 Internal Server Error`:
     36     The server experienced an internal failure.
     37     Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED`` or
     38     ``TALER_EC_GENERIC_FAILED_COMPUTE_JSON_HASH``.
     39 
     40   **Details:**
     41 
     42   .. ts:def:: WalletRefundRequest
     43 
     44     interface WalletRefundRequest {
     45       // Hash of the order's contract terms (this is used to authenticate the
     46       // wallet/customer).
     47       h_contract: HashCode;
     48     }
     49 
     50   .. ts:def:: WalletRefundResponse
     51 
     52     interface WalletRefundResponse {
     53       // Amount that was refunded in total.
     54       refund_amount: Amount;
     55 
     56       // Successful refunds for this payment, empty array for none.
     57       refunds: MerchantCoinRefundStatus[];
     58 
     59       // Public key of the merchant.
     60       merchant_pub: EddsaPublicKey;
     61 
     62     }
     63 
     64   .. ts:def:: MerchantCoinRefundStatus
     65 
     66     type MerchantCoinRefundStatus =
     67       | MerchantCoinRefundSuccessStatus
     68       | MerchantCoinRefundFailureStatus;
     69 
     70   .. ts:def:: MerchantCoinRefundFailureStatus
     71 
     72     // Details about why a refund failed.
     73     interface MerchantCoinRefundFailureStatus {
     74       // Used as tag for the sum type RefundStatus sum type.
     75       type: "failure";
     76 
     77       // HTTP status of the exchange request, must NOT be 200.
     78       exchange_status: Integer;
     79 
     80       // Taler error code from the exchange reply, if available.
     81       exchange_code?: Integer;
     82 
     83       // If available, HTTP reply from the exchange.
     84       exchange_reply?: Object;
     85 
     86       // Refund transaction ID.
     87       rtransaction_id: Integer;
     88 
     89       // Public key of a coin that was refunded.
     90       coin_pub: EddsaPublicKey;
     91 
     92       // Amount that was refunded, including refund fee charged by the exchange
     93       // to the customer.
     94       refund_amount: Amount;
     95 
     96       // Timestamp when the merchant approved the refund.
     97       // Useful for grouping refunds.
     98       execution_time: Timestamp;
     99     }
    100 
    101   .. ts:def:: MerchantCoinRefundSuccessStatus
    102 
    103     // Additional details needed to verify the refund confirmation signature
    104     // (``h_contract_terms`` and ``merchant_pub``) are already known
    105     // to the wallet and thus not included.
    106     interface MerchantCoinRefundSuccessStatus {
    107       // Used as tag for the sum type MerchantCoinRefundStatus sum type.
    108       type: "success";
    109 
    110       // HTTP status of the exchange request, 200 (integer) required for refund confirmations.
    111       exchange_status: 200;
    112 
    113       // The EdDSA :ref:`signature` (binary-only) with purpose
    114       // `TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND` using a current signing key of the
    115       // exchange affirming the successful refund.
    116       exchange_sig: EddsaSignature;
    117 
    118       // Public EdDSA key of the exchange that was used to generate the signature.
    119       // Should match one of the exchange's signing keys from /keys.  It is given
    120       // explicitly as the client might otherwise be confused by clock skew as to
    121       // which signing key was used.
    122       exchange_pub: EddsaPublicKey;
    123 
    124       // Refund transaction ID.
    125       rtransaction_id: Integer;
    126 
    127       // Public key of a coin that was refunded.
    128       coin_pub: EddsaPublicKey;
    129 
    130       // Amount that was refunded, including refund fee charged by the exchange
    131       // to the customer.
    132       refund_amount: Amount;
    133 
    134       // Timestamp when the merchant approved the refund.
    135       // Useful for grouping refunds.
    136       execution_time: Timestamp;
    137     }