taler-docs

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

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

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