taler-docs

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

post-orders-ORDER_ID-abort.rst (6822B)

      1 .. http:post:: [/instances/$INSTANCE]/orders/$ORDER_ID/abort
      2 
      3   Abort paying for an order and obtain a refund for coins that
      4   were already deposited as part of a failed payment.
      5 
      6   **Request:**
      7 
      8   The request must be an `abort request <AbortRequest>`.  We force the wallet
      9   to specify the affected coins as it may only request for a subset of the coins
     10   (i.e. because the wallet knows that some were double-spent causing the failure).
     11   Also we need to know the coins because there may be two wallets "competing" over
     12   the same order and one wants to abort while the other still proceeds with the
     13   payment. Here we need to again know which subset of the deposits to abort.
     14 
     15   **Response:**
     16 
     17   :http:statuscode:`200 OK`:
     18     The merchant accepted the request, and passed it on to the exchange(s).
     19     The body is an
     20     `abort response <AbortResponse>`.
     21     Note that the exchange MAY still have encountered errors in processing.
     22     Those will then be part of the body.
     23     Wallets MUST carefully consider errors for each of the coins as
     24     returned by the exchange.
     25   :http:statuscode:`400 Bad request`:
     26     Either the client request is malformed or some specific processing error
     27     happened that may be the fault of the client as detailed in the JSON body
     28     of the response.
     29     Returned with ``TALER_EC_MERCHANT_POST_ORDERS_ID_ABORT_COINS_ARRAY_EMPTY`` or
     30     ``TALER_EC_MERCHANT_POST_ORDERS_ID_ABORT_CONTRACT_HASH_MISSMATCH``.
     31   :http:statuscode:`403 Forbidden`:
     32     The ``h_contract`` does not match the $ORDER_ID.
     33   :http:statuscode:`404 Not found`:
     34     The merchant backend could not find the order or the instance
     35     and thus cannot process the abort request.
     36     Returned with ``TALER_EC_MERCHANT_POST_ORDERS_ID_ABORT_CONTRACT_NOT_FOUND``.
     37   :http:statuscode:`408 Request timeout`:
     38     The merchant backend took too long getting a response from the exchange.
     39     The wallet SHOULD retry soon.
     40   :http:statuscode:`412 Precondition failed`:
     41     Aborting the payment is not allowed, as the original payment did succeed.
     42     It is possible that a different wallet succeeded with the payment. This
     43     wallet should thus try to refresh all of the coins involved in the payment.
     44     Returned with ``TALER_EC_MERCHANT_POST_ORDERS_ID_ABORT_REFUND_REFUSED_PAYMENT_COMPLETE``.
     45   :http:statuscode:`413 Request entity too large`:
     46     The uploaded body is to long, it exceeds the size limit.
     47     Returned with an error code of
     48     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     49   :http:statuscode:`500 Internal Server Error`:
     50     The server experienced an internal failure.
     51     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``,
     52     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     53     ``TALER_EC_GENERIC_DB_START_FAILED``,
     54     ``TALER_EC_GENERIC_DB_COMMIT_FAILED`` or
     55     ``TALER_EC_GENERIC_DB_SOFT_FAILURE``.
     56   :http:statuscode:`502 Bad gateway`:
     57     The merchant's interaction with some exchange failed in some way.
     58     The errors from the exchanges are included.
     59     The body is a `abort response <AbortResponse>`.
     60     Note that the exchange MAY still have encountered errors in processing.
     61     Those will then be part of the body.
     62     Wallets MUST carefully consider errors for each of the coins as
     63     returned by the exchange.
     64   :http:statuscode:`504 Gateway timeout`:
     65     The merchant's interaction with the exchange took too long.
     66     The client might want to try again later.
     67 
     68   The backend will return an `abort response <AbortResponse>`, which includes
     69   verbatim the error codes received from the exchange's
     70   :ref:`refund <exchange_refund>` API.  The frontend should pass the replies verbatim to
     71   the browser/wallet.
     72 
     73   **Details:**
     74 
     75   .. ts:def:: AbortRequest
     76 
     77     interface AbortRequest {
     78 
     79       // Hash of the order's contract terms (this is used to authenticate the
     80       // wallet/customer in case $ORDER_ID is guessable).
     81       h_contract: HashCode;
     82 
     83       // List of coins the wallet would like to see refunds for.
     84       // (Should be limited to the coins for which the original
     85       // payment succeeded, as far as the wallet knows.)
     86       coins: AbortingCoin[];
     87     }
     88 
     89   .. ts:def:: AbortingCoin
     90 
     91     interface AbortingCoin {
     92       // Public key of a coin for which the wallet is requesting an abort-related refund.
     93       coin_pub: EddsaPublicKey;
     94 
     95       // URL of the exchange this coin was withdrawn from.
     96       exchange_url: string;
     97     }
     98 
     99 
    100   .. ts:def:: AbortResponse
    101 
    102     interface AbortResponse {
    103 
    104       // List of refund responses about the coins that the wallet
    105       // requested an abort for.  In the same order as the ``coins``
    106       // from the original request.
    107       // The ``rtransaction_id`` is implied to be 0.
    108       refunds: MerchantAbortPayRefundStatus[];
    109     }
    110 
    111   .. ts:def:: MerchantAbortPayRefundStatus
    112 
    113     type MerchantAbortPayRefundStatus =
    114       | MerchantAbortPayRefundSuccessStatus
    115       | MerchantAbortPayRefundUndepositedStatus
    116       | MerchantAbortPayRefundFailureStatus;
    117 
    118   .. ts:def:: MerchantAbortPayRefundFailureStatus
    119 
    120     // Details about why a refund failed.
    121     interface MerchantAbortPayRefundFailureStatus {
    122       // Used as tag for the sum type RefundStatus sum type.
    123       type: "failure";
    124 
    125       // HTTP status of the exchange request, must NOT be 200.
    126       exchange_status: Integer;
    127 
    128       // Taler error code from the exchange reply, if available.
    129       exchange_code?: Integer;
    130 
    131       // If available, HTTP reply from the exchange.
    132       exchange_reply?: Object;
    133     }
    134 
    135   .. ts:def:: MerchantAbortPayRefundSuccessStatus
    136 
    137     // Additional details needed to verify the refund confirmation signature
    138     // (``h_contract_terms`` and ``merchant_pub``) are already known
    139     // to the wallet and thus not included.
    140     interface MerchantAbortPayRefundSuccessStatus {
    141       // Used as tag for the sum type MerchantCoinRefundStatus sum type.
    142       type: "success";
    143 
    144       // HTTP status of the exchange request, 200 (integer) required for refund confirmations.
    145       exchange_status: 200;
    146 
    147       // The EdDSA :ref:`signature` (binary-only) with purpose
    148       // `TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND` using a current signing key of the
    149       // exchange affirming the successful refund.
    150       exchange_sig: EddsaSignature;
    151 
    152       // Public EdDSA key of the exchange that was used to generate the signature.
    153       // Should match one of the exchange's signing keys from ``/keys``.  It is given
    154       // explicitly as the client might otherwise be confused by clock skew as to
    155       // which signing key was used.
    156       exchange_pub: EddsaPublicKey;
    157     }
    158 
    159   .. ts:def:: MerchantAbortPayRefundUndepositedStatus
    160 
    161     // The merchant didn't deposit the coin in the first place,
    162     // no refund possible.
    163     interface MerchantAbortPayRefundSuccessStatus {
    164       // Used as tag for the sum type MerchantCoinRefundStatus sum type.
    165       type: "undeposited";
    166     }