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