taler-docs

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

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

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