POST /withdraw

Withdraw multiple coins from the same reserve. Note that the client should commit all of the request details, including the private key of the coins and the blinding factors, to disk before issuing this request, so that it can recover the information if necessary in case of transient failures, like power outage, network outage, etc.

Request:

The request body must be a WithdrawRequest object.

Response:

200 OK:

The request was successful, and max_age was not set. The response is a WithdrawResponse. Note that repeating exactly the same request will again yield the same response, so if the network goes down during the transaction or before the client can commit the coins signature to disk, the coins are not lost.

201 Created:

The request was successful, and max_age was set. The response is a AgeWithdrawResponse. The client is expected to call /reveal-withdraw next. Note that repeating exactly the same request will again yield the same response, so if the network goes down during the transaction or before the client can commit the coins signature to disk, the coins are not lost.

400 Bad Request:

The request body is malformed or a parameter is invalid. This response comes with a standard ErrorDetail response. Possible error codes include TALER_EC_GENERIC_PARAMETER_MALFORMED, TALER_EC_GENERIC_PARAMETER_MISSING, TALER_EC_EXCHANGE_GENERIC_CIPHER_MISMATCH, TALER_EC_EXCHANGE_WITHDRAW_AMOUNT_OVERFLOW, or TALER_EC_EXCHANGE_WITHDRAW_IDEMPOTENT_PLANCHET.

403 Forbidden:

A signature is invalid. This is usually the reserve signature. This response comes with a standard ErrorDetail response with a code of TALER_EC_EXCHANGE_WITHDRAW_RESERVE_SIGNATURE_INVALID.

404 Not found:

One of the following reasons occured:

1. The reserve is unknown. The response comes with a standard ErrorDetail response with error-code TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN. If the reserve is unknown, the wallet should not report a hard error, but instead long-poll for the reserve status to wait for the wire transfer to complete. Once the wire transfer has arrived, the wallet should repeat the exact same request later again, possibly using exactly the same blinded coins.

2. A denomination keyis not known to the exchange. The response comes with a standard ErrorDetail response with error-code TALER_EC_EXCHANGE_GENERIC_DENOMINATION_KEY_UNKNOWN. This suggests the wallet has outdated /keys and should fetch the latest /keys.

409 Conflict:

One of the following reasons occured:

1. The balance of the reserve is not sufficient to withdraw the coins of the indicated denominations. The response is WithdrawError object with an error code of TALER_EC_EXCHANGE_WITHDRAW_INSUFFICIENT_FUNDS. An operation withdrawing less money should succeed.

2. The reserve has a birthday set and requires the request to provide a max_age value. The response comes with a standard ErrorDetail response with an error-code of TALER_EC_EXCHANGE_RESERVES_AGE_RESTRICTION_REQUIRED and an additional field maximum_allowed_age for the maximum age (in years) that the client can commit to in a call to /withdraw, this time with max_age set accordingly and coin_evs being an array of n*kappa elements of type CoinEnvelope.

3. The provided value for max_age is higher than the allowed value according to the reserve’s birthday. The response comes with a standard ErrorDetail response with error-code TALER_EC_EXCHANGE_WITHDRAW_MAXIMUM_AGE_TOO_LARGE and additional fields allowed_maximum_age for the maximum age (in years) that the client can commit to in a call to /withdraw, and reserve_birthday with the reserve’s birthday value.

4. The request uses a nonce value that was previously seen by the exchange for a different request. As nonces must be unique, the request is rejected with TALER_EC_EXCHANGE_WITHDRAW_NONCE_REUSE. This can only happen with some cipher types that use nonces.

410 Gone:

A requested denomination key is no longer valid. There are two cases:

1. The denomination key is past its expiration. The response is a DenominationGoneMessage with a code of TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED.

2. The denominatoin key was revoked. The response is a plain ErrorDetail with a code of TALER_EC_EXCHANGE_GENERIC_DENOMINATION_REVOKED.

412 Precondition Failed:

A requested denomination key is not yet valid. It is before the validity start time. The response is a DenominationGoneMessage with TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE. A common case might be a difference in the current time between wallet and exchange. The wallet could probably just wait a bit and retry. Checking the server’s Date: header should allow the wallet to figure out how long to wait. Alternatively, the wallet could try with an the previous denomination key generation. Note: this is a bit of an abuse of the HTTP status code.

413 Request entity too large:

The uploaded body is to long, it exceeds the size limit. Returned with an error code of TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT.

451 Unavailable for Legal Reasons:

This reserve has received funds from a purse or the amount withdrawn exceeds another legal threshold and thus the reserve must be upgraded to an account (with KYC) before the withdraw can complete. Note that this response does NOT affirm that the withdraw will ultimately complete with the requested amount. The user should be redirected to the provided location to perform the required KYC checks to open the account before withdrawing. Afterwards, the request should be repeated. The response will be an LegitimizationNeededResponse object.

Implementation note: internally, we need to distinguish between upgrading the reserve to an account (due to P2P payment) and identifying the owner of the origin bank account (due to exceeding the withdraw amount threshold), as we need to create a different payto://-URI for the KYC check depending on the case.

500 Internal Server Error:

The exchange encountered an internal error during the withdrawal. This response comes with a standard ErrorDetail response. Possible error codes include TALER_EC_GENERIC_DB_FETCH_FAILED, TALER_EC_GENERIC_DB_INVARIANT_FAILURE, TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE, TALER_EC_EXCHANGE_WITHDRAW_AMOUNT_FEE_OVERFLOW, or TALER_EC_EXCHANGE_WITHDRAW_AMOUNT_OVERFLOW.

501 Not implemented:

The client has provided a cipher that is not supported.

502 Bad gateway:

This indicates the exchange could not communicate with an external process. This usually means the exchange could not talk to one of its secmod helpers. Here, a standard error message with a code of TALER_EC_EXCHANGE_SIGNKEY_HELPER_UNAVAILABLE is returned. Wallets should retry the requests (with some delays) at a later time.

503 Service Unavailable:

This primarily happens when the exchange currently has no denomination signing keys at all, for example because the offline signature did not yet happen. In this case, a standard error message with a code of TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING is returned.

Details: