taler-docs

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

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

      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:`500 Internal Server Error`:
     32     The server experienced an internal failure.
     33     Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
     34 
     35   **Details:**
     36 
     37   .. ts:def:: WalletRefundRequest
     38 
     39     interface WalletRefundRequest {
     40       // Hash of the order's contract terms (this is used to authenticate the
     41       // wallet/customer).
     42       h_contract: HashCode;
     43     }
     44 
     45   .. ts:def:: WalletRefundResponse
     46 
     47     interface WalletRefundResponse {
     48       // Amount that was refunded in total.
     49       refund_amount: Amount;
     50 
     51       // Successful refunds for this payment, empty array for none.
     52       refunds: MerchantCoinRefundStatus[];
     53 
     54       // Public key of the merchant.
     55       merchant_pub: EddsaPublicKey;
     56 
     57     }
     58 
     59   .. ts:def:: MerchantCoinRefundStatus
     60 
     61     type MerchantCoinRefundStatus =
     62       | MerchantCoinRefundSuccessStatus
     63       | MerchantCoinRefundFailureStatus;
     64 
     65   .. ts:def:: MerchantCoinRefundFailureStatus
     66 
     67     // Details about why a refund failed.
     68     interface MerchantCoinRefundFailureStatus {
     69       // Used as tag for the sum type RefundStatus sum type.
     70       type: "failure";
     71 
     72       // HTTP status of the exchange request, must NOT be 200.
     73       exchange_status: Integer;
     74 
     75       // Taler error code from the exchange reply, if available.
     76       exchange_code?: Integer;
     77 
     78       // If available, HTTP reply from the exchange.
     79       exchange_reply?: Object;
     80 
     81       // Refund transaction ID.
     82       rtransaction_id: Integer;
     83 
     84       // Public key of a coin that was refunded.
     85       coin_pub: EddsaPublicKey;
     86 
     87       // Amount that was refunded, including refund fee charged by the exchange
     88       // to the customer.
     89       refund_amount: Amount;
     90 
     91       // Timestamp when the merchant approved the refund.
     92       // Useful for grouping refunds.
     93       execution_time: Timestamp;
     94     }
     95 
     96   .. ts:def:: MerchantCoinRefundSuccessStatus
     97 
     98     // Additional details needed to verify the refund confirmation signature
     99     // (``h_contract_terms`` and ``merchant_pub``) are already known
    100     // to the wallet and thus not included.
    101     interface MerchantCoinRefundSuccessStatus {
    102       // Used as tag for the sum type MerchantCoinRefundStatus sum type.
    103       type: "success";
    104 
    105       // HTTP status of the exchange request, 200 (integer) required for refund confirmations.
    106       exchange_status: 200;
    107 
    108       // The EdDSA :ref:`signature` (binary-only) with purpose
    109       // `TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND` using a current signing key of the
    110       // exchange affirming the successful refund.
    111       exchange_sig: EddsaSignature;
    112 
    113       // Public EdDSA key of the exchange that was used to generate the signature.
    114       // Should match one of the exchange's signing keys from /keys.  It is given
    115       // explicitly as the client might otherwise be confused by clock skew as to
    116       // which signing key was used.
    117       exchange_pub: EddsaPublicKey;
    118 
    119       // Refund transaction ID.
    120       rtransaction_id: Integer;
    121 
    122       // Public key of a coin that was refunded.
    123       coin_pub: EddsaPublicKey;
    124 
    125       // Amount that was refunded, including refund fee charged by the exchange
    126       // to the customer.
    127       refund_amount: Amount;
    128 
    129       // Timestamp when the merchant approved the refund.
    130       // Useful for grouping refunds.
    131       execution_time: Timestamp;
    132     }