taler-docs

post-reserves-RESERVE_PUB-open.rst (5348B)

---

 .. http:post:: /reserves/$RESERVE_PUB/open
 
   Request keeping a reserve open for invoicing.
 
   **Request:**
 
   The request body must be a `ReserveOpenRequest` object.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The exchange responds with a `ReserveOpenResponse` object.
   :http:statuscode:`400 Bad Request`:
     The request timestamp has excessive clock skew.
     This response comes with a standard `ErrorDetail` response with
     a code of ``TALER_EC_EXCHANGE_GENERIC_CLOCK_SKEW``.
   :http:statuscode:`402 Payment Required`:
     The exchange responds with a `ReserveOpenFailure` object when
     the payment offered is insufficient for the requested operation.
   :http:statuscode:`403 Forbidden`:
     The *TALER_SIGNATURE_WALLET_RESERVE_OPEN* signature is invalid.
     This response comes with a standard `ErrorDetail` response with
     a code of ``TALER_EC_EXCHANGE_RESERVES_OPEN_BAD_SIGNATURE``.
   :http:statuscode:`404 Not found`:
     The reserve key does not belong to a reserve known to the exchange.
     This response comes with a standard `ErrorDetail` response with
     a code of ``TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN``.
   :http:statuscode:`409 Conflict`:
     The balance of the reserve or of a coin was insufficient.
     Which case it is can be decided by looking at the error code
     (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or
     ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` or
     ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_AGE_HASH`` or
     ``TALER_EC_EXCHANGE_RESERVES_OPEN_INSUFFICIENT_FUNDS``).
     The specific fields of the response depend on the error code
     and include the signatures (and what was signed over) proving the
     conflict.
     The response is a `WithdrawError` object, a `DepositDoubleSpendError`,
     a `CoinDenominationConflictError` or a `CoinAgeCommitmentConflictError`
     depending on the error type.
   :http:statuscode:`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``.
   :http:statuscode:`500 Internal Server Error`:
     The exchange encountered an internal error.
     This response comes with a standard `ErrorDetail` response.
     Possible error codes include
     ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING``,
     ``TALER_EC_EXCHANGE_GENERIC_BAD_CONFIGURATION``,
     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     ``TALER_EC_GENERIC_DB_STORE_FAILED``, or
     ``TALER_EC_GENERIC_FAILED_COMPUTE_AMOUNT``.
 
   **Details:**
 
   .. ts:def:: ReserveOpenRequest
 
     interface ReserveOpenRequest {
       // Signature of purpose
       // ``TALER_SIGNATURE_WALLET_RESERVE_OPEN`` over
       // a `TALER_ReserveOpenPS`.
       reserve_sig: EddsaSignature;
 
       // Array of payments made towards the cost of the
       // operation.
       payments: OpenPaymentDetail[];
 
       // Amount to be paid from the reserve for this
       // operation.
       reserve_payment: Amount;
 
       // Time when the client made the request.
       // Timestamp must be reasonably close to the time of
       // the exchange, otherwise the exchange may reject
       // the request (with a status code of 400).
       request_timestamp: Timestamp;
 
       // Desired new expiration time for the reserve.
       // If the reserve would expire before this time,
       // the exchange will charge account fees (and
       // possibly KYC fees) until the expiration time
       // exceeds this timestamp. Note that the exchange
       // will refuse requests (with a status code of 400)
       // if the time is so far in the future that the
       // fees are not yet known (see /keys).
       reserve_expiration: Timestamp;
 
       // Desired open purse limit. Can be used to pay the
       // annual account fee more than once to get a larger
       // purse limit.
       purse_limit: Integer;
 
     }
 
   .. ts:def:: ReserveOpenResponse
 
     interface ReserveOpenResponse {
       // Transaction cost for extending the expiration time.
       // Excludes KYC fees.
       open_cost: Amount;
 
       // Current expiration time for the reserve.
       reserve_expiration: Timestamp;
     }
 
   .. ts:def:: ReserveOpenFailure
 
     interface ReserveOpenFailure {
       // Transaction cost that should have been paid
       // to extending the reserve as requested.
       // Excludes KYC fees.
       open_cost: Amount;
 
       // Remaining expiration time for the reserve.
       reserve_expiration: Timestamp;
     }
 
   .. ts:def:: OpenPaymentDetail
 
     interface OpenPaymentDetail {
 
       // Contribution of this coin to the overall amount.
       // Can be a fraciton of the coin's total value.
       amount: Amount;
 
       // Hash of denomination RSA key with which the coin is signed.
       denom_pub_hash: HashCode;
 
       // Exchange's unblinded RSA signature of the coin.
       ub_sig: DenominationSignature;
 
       // Age commitment for the coin, if the denomination is age-restricted.
       age_commitment?: AgeCommitment;
 
       // Signature over `TALER_ReserveOpenDepositSignaturePS`
       // of purpose ``TALER_SIGNATURE_WALLET_RESERVE_OPEN_DEPOSIT``
       // made by the customer with the
       // `coin's private key <coin-priv>`.
       coin_sig: EddsaSignature;
 
       // Public key of the coin being used to pay for
       // opening the reserve.
       coin_pub: EddsaPublicKey;
 
     }