taler-docs

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

post-withdraw.rst (6905B)

      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 ``/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:`403 Forbidden`:
     29     A signature is invalid. This is usually the reserve signature.
     30     This response comes with a standard `ErrorDetail` response with
     31     a code of ``TALER_EC_EXCHANGE_WITHDRAW_RESERVE_SIGNATURE_INVALID``.
     32   :http:statuscode:`404 Not found`:
     33     One of the following reasons occured:
     34 
     35     1. The reserve is unknown. The response comes with a standard
     36        `ErrorDetail` response with error-code
     37        ``TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN``.
     38        If the reserve is unknown, the wallet should not report a
     39        hard error, but instead long-poll for the reserve status to wait
     40        for the wire transfer to complete.
     41        Once the wire transfer has arrived,
     42        the wallet should repeat the exact same request later again,
     43        possibly using exactly the same blinded coins.
     44     2. A denomination keyis not known to the exchange.
     45        The response comes with a standard
     46        `ErrorDetail` response with error-code
     47        ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_KEY_UNKNOWN``.
     48        This suggests the wallet has outdated ``/keys`` and
     49        should fetch the latest ``/keys``.
     50   :http:statuscode:`409 Conflict`:
     51     One of the following reasons occured:
     52 
     53     1. The balance of the reserve is not sufficient to withdraw the
     54        coins of the indicated denominations.
     55        The response is `WithdrawError` object with an error code of
     56        ``TALER_EC_EXCHANGE_WITHDRAW_INSUFFICIENT_FUNDS``.  An operation
     57        withdrawing less money should succeed.
     58     2. The reserve has a birthday set and requires the request to
     59        provide a ``max_age``  value.
     60        The response comes with a standard `ErrorDetail` response with
     61        an error-code of
     62        ``TALER_EC_EXCHANGE_RESERVES_AGE_RESTRICTION_REQUIRED``
     63        and an additional field ``maximum_allowed_age`` for the
     64        maximum age (in years)
     65        that the client can commit to in a call to ``/withdraw``, this time
     66        with ``max_age`` set accordingly and ``coin_evs`` being an array
     67        of ``n*kappa`` elements of type `CoinEnvelope`.
     68     3. The provided value for ``max_age`` is higher than the allowed value
     69        according to the reserve's birthday. The response comes with a
     70        standard `ErrorDetail` response with error-code
     71        ``TALER_EC_EXCHANGE_AGE_WITHDRAW_MAXIMUM_AGE_TOO_LARGE``
     72        and an additional field ``maximum_allowed_age`` for the maximum
     73        age (in years) that the client can commit to in a call
     74        to ``/withdraw``.
     75     4. The request uses a nonce value that was previously seen by
     76        the exchange for a different request. As nonces must be unique,
     77        the request is rejected. This can only happen with some cipher
     78        types that use nonces.
     79   :http:statuscode:`410 Gone`:
     80     A requested denomination key is no longer valid. There are two cases:
     81 
     82     1. The denomination key is past its expiration.
     83        The response is a `DenominationGoneMessage` with a code of
     84        ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED``.
     85     2. The denominatoin key was revoked. The response is a
     86        plain `ErrorDetail` with a code of ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_REVOKED``.
     87   :http:statuscode:`412 Precondition Failed`:
     88     A requested denomination key is not yet valid.
     89     It is before the validity start time.
     90     The response is a `DenominationGoneMessage` with
     91     ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE``.
     92     A common case might be a difference in the current time between
     93     wallet and exchange. The wallet could probably just wait a bit and
     94     retry. Checking the server's ``Date:`` header should allow the
     95     wallet to figure out how long to wait. Alternatively, the wallet
     96     could try with an the previous denomination key generation.
     97     Note: this is a bit of an abuse of the HTTP status code.
     98   :http:statuscode:`451 Unavailable for Legal Reasons`:
     99     This reserve has received funds from a purse or the amount withdrawn
    100     exceeds another legal threshold and thus the reserve must
    101     be upgraded to an account (with KYC) before the withdraw can
    102     complete.  Note that this response does NOT affirm that the
    103     withdraw will ultimately complete with the requested amount.
    104     The user should be redirected to the provided location to perform
    105     the required KYC checks to open the account before withdrawing.
    106     Afterwards, the request should be repeated.
    107     The response will be an `LegitimizationNeededResponse` object.
    108 
    109     Implementation note: internally, we need to
    110     distinguish between upgrading the reserve to an
    111     account (due to P2P payment) and identifying the
    112     owner of the origin bank account (due to exceeding
    113     the withdraw amount threshold), as we need to create
    114     a different payto://-URI for the KYC check depending
    115     on the case.
    116   :http:statuscode:`501 Not implemented`:
    117     The client has provided a cipher that is not supported.
    118   :http:statuscode:`502 Bad gateway`:
    119     This indicates the exchange could not communicate with an
    120     external process. This usually means the exchange could
    121     not talk to one of its secmod helpers.
    122     Here, a standard error message with a code of
    123     ``TALER_EC_EXCHANGE_SIGNKEY_HELPER_UNAVAILABLE``
    124     is returned.
    125     Wallets should retry the requests (with some delays) at
    126     a later time.
    127   :http:statuscode:`503 Service Unavailable`:
    128     This primarily happens when the exchange currently has no
    129     denomination signing keys at all, for example because the
    130     offline signature did not yet happen. In this case, a standard
    131     error message with a code of
    132     ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING`` is returned.
    133 
    134   **Details:**