taler-docs

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

post-withdraw.rst (8371B)


      1 .. http:post:: /withdraw
      2 
      3   Withdraw multiple coins from the same reserve.  Note that the client should
      4   commit all of the request details, including the private key of the coins and
      5   the blinding factors, to disk *before* issuing this request, so that it can
      6   recover the information if necessary in case of transient failures, like
      7   power outage, network outage, etc.
      8 
      9   **Request:**
     10 
     11   The request body must be a `WithdrawRequest` object.
     12 
     13   **Response:**
     14 
     15   :http:statuscode:`200 OK`:
     16     The request was successful, and ``max_age`` was not set.
     17     The response is a `WithdrawResponse`.
     18     Note that repeating exactly the same request will again yield the same
     19     response, so if the network goes down during the transaction or before the
     20     client can commit the coins signature to disk, the coins are not lost.
     21   :http:statuscode:`201 Created`:
     22     The request was successful, and ``max_age`` was set.
     23     The response is a `AgeWithdrawResponse`.  The client is expected
     24     to call :http:post:`/reveal-withdraw </reveal-withdraw>` next.
     25     Note that repeating exactly the same request will again yield the same
     26     response, so if the network goes down during the transaction or before the
     27     client can commit the coins signature to disk, the coins are not lost.
     28   :http:statuscode:`400 Bad Request`:
     29     The request body is malformed or a parameter is invalid.
     30     This response comes with a standard `ErrorDetail` response.
     31     Possible error codes include ``TALER_EC_GENERIC_PARAMETER_MALFORMED``,
     32     ``TALER_EC_GENERIC_PARAMETER_MISSING``,
     33     ``TALER_EC_EXCHANGE_GENERIC_CIPHER_MISMATCH``,
     34     ``TALER_EC_EXCHANGE_WITHDRAW_AMOUNT_OVERFLOW``, or
     35     ``TALER_EC_EXCHANGE_WITHDRAW_IDEMPOTENT_PLANCHET``.
     36     A Clause-Schnorr envelope whose ``cs_nonce`` is not the one derived
     37     from ``blinding_seed`` is refused with
     38     ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` (since **v46**).
     39   :http:statuscode:`403 Forbidden`:
     40     A signature is invalid. This is usually the reserve signature.
     41     This response comes with a standard `ErrorDetail` response with
     42     a code of ``TALER_EC_EXCHANGE_WITHDRAW_RESERVE_SIGNATURE_INVALID``.
     43   :http:statuscode:`404 Not found`:
     44     One of the following reasons occured:
     45 
     46     1. The reserve is unknown. The response comes with a standard
     47        `ErrorDetail` response with error-code
     48        ``TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN``.
     49        If the reserve is unknown, the wallet should not report a
     50        hard error, but instead long-poll for the reserve status to wait
     51        for the wire transfer to complete.
     52        Once the wire transfer has arrived,
     53        the wallet should repeat the exact same request later again,
     54        possibly using exactly the same blinded coins.
     55     2. A denomination keyis not known to the exchange.
     56        The response comes with a standard
     57        `ErrorDetail` response with error-code
     58        ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_KEY_UNKNOWN``.
     59        This suggests the wallet has outdated :http:get:`/keys </keys>` and
     60        should fetch the latest :http:get:`/keys </keys>`.
     61   :http:statuscode:`409 Conflict`:
     62     One of the following reasons occured:
     63 
     64     1. The balance of the reserve is not sufficient to withdraw the
     65        coins of the indicated denominations.
     66        The response is `WithdrawError` object with an error code of
     67        ``TALER_EC_EXCHANGE_WITHDRAW_INSUFFICIENT_FUNDS``.  An operation
     68        withdrawing less money should succeed.
     69     2. The reserve has a birthday set and requires the request to
     70        provide a ``max_age``  value.
     71        The response comes with a standard `ErrorDetail` response with
     72        an error-code of
     73        ``TALER_EC_EXCHANGE_RESERVES_AGE_RESTRICTION_REQUIRED``
     74        and an additional field ``maximum_allowed_age`` for the
     75        maximum age (in years)
     76        that the client can commit to in a call to ``/withdraw``, this time
     77        with ``max_age`` set accordingly and ``coin_evs`` being an array
     78        of ``n*kappa`` elements of type `CoinEnvelope`.
     79     3. The provided value for ``max_age`` is higher than the allowed value
     80        according to the reserve's birthday. The response comes with a
     81        standard `ErrorDetail` response with error-code
     82        ``TALER_EC_EXCHANGE_WITHDRAW_MAXIMUM_AGE_TOO_LARGE``
     83        and additional fields ``allowed_maximum_age`` for the maximum
     84        age (in years) that the client can commit to in a call
     85        to ``/withdraw``, and ``reserve_birthday`` with the
     86        reserve's birthday value.
     87     4. The request uses a nonce value that was previously seen by
     88        the exchange for a different request. As nonces must be unique,
     89        the request is rejected with
     90        ``TALER_EC_EXCHANGE_WITHDRAW_NONCE_REUSE``.
     91        This can only happen with some cipher
     92        types that use nonces.
     93   :http:statuscode:`410 Gone`:
     94     A requested denomination key is no longer valid. There are two cases:
     95 
     96     1. The denomination key is past its expiration.
     97        The response is a `DenominationGoneMessage` with a code of
     98        ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED``.
     99     2. The denominatoin key was revoked. The response is a
    100        plain `ErrorDetail` with a code of ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_REVOKED``.
    101   :http:statuscode:`412 Precondition Failed`:
    102     A requested denomination key is not yet valid.
    103     It is before the validity start time.
    104     The response is a `DenominationGoneMessage` with
    105     ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE``.
    106     A common case might be a difference in the current time between
    107     wallet and exchange. The wallet could probably just wait a bit and
    108     retry. Checking the server's ``Date:`` header should allow the
    109     wallet to figure out how long to wait. Alternatively, the wallet
    110     could try with an the previous denomination key generation.
    111     Note: this is a bit of an abuse of the HTTP status code.
    112   :http:statuscode:`413 Request entity too large`:
    113     The uploaded body is to long, it exceeds the size limit.
    114     Returned with an error code of
    115     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
    116   :http:statuscode:`451 Unavailable for Legal Reasons`:
    117     This reserve has received funds from a purse or the amount withdrawn
    118     exceeds another legal threshold and thus the reserve must
    119     be upgraded to an account (with KYC) before the withdraw can
    120     complete.  Note that this response does NOT affirm that the
    121     withdraw will ultimately complete with the requested amount.
    122     The user should be redirected to the provided location to perform
    123     the required KYC checks to open the account before withdrawing.
    124     Afterwards, the request should be repeated.
    125     The response will be an `LegitimizationNeededResponse` object.
    126 
    127     Implementation note: internally, we need to
    128     distinguish between upgrading the reserve to an
    129     account (due to P2P payment) and identifying the
    130     owner of the origin bank account (due to exceeding
    131     the withdraw amount threshold), as we need to create
    132     a different payto://-URI for the KYC check depending
    133     on the case.
    134   :http:statuscode:`500 Internal Server Error`:
    135     The exchange encountered an internal error during the withdrawal.
    136     This response comes with a standard `ErrorDetail` response.
    137     Possible error codes include
    138     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
    139     ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``,
    140     ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``,
    141     ``TALER_EC_EXCHANGE_WITHDRAW_AMOUNT_FEE_OVERFLOW``, or
    142     ``TALER_EC_EXCHANGE_WITHDRAW_AMOUNT_OVERFLOW``.
    143   :http:statuscode:`501 Not implemented`:
    144     The client has provided a cipher that is not supported.
    145   :http:statuscode:`502 Bad gateway`:
    146     This indicates the exchange could not communicate with an
    147     external process. This usually means the exchange could
    148     not talk to one of its secmod helpers.
    149     Here, a standard error message with a code of
    150     ``TALER_EC_EXCHANGE_SIGNKEY_HELPER_UNAVAILABLE``
    151     is returned.
    152     Wallets should retry the requests (with some delays) at
    153     a later time.
    154   :http:statuscode:`503 Service Unavailable`:
    155     This primarily happens when the exchange currently has no
    156     denomination signing keys at all, for example because the
    157     offline signature did not yet happen. In this case, a standard
    158     error message with a code of
    159     ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING`` is returned.
    160 
    161   **Details:**