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:**