taler-docs

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

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

      1 .. http:post:: /reserves/$RESERVE_PUB/open
      2 
      3   Request keeping a reserve open for invoicing.
      4 
      5   **Request:**
      6 
      7   The request body must be a `ReserveOpenRequest` object.
      8 
      9   **Response:**
     10 
     11   :http:statuscode:`200 OK`:
     12     The exchange responds with a `ReserveOpenResponse` object.
     13   :http:statuscode:`402 Payment Required`:
     14     The exchange responds with a `ReserveOpenFailure` object when
     15     the payment offered is insufficient for the requested operation.
     16   :http:statuscode:`403 Forbidden`:
     17     The *TALER_SIGNATURE_WALLET_RESERVE_OPEN* signature is invalid.
     18     This response comes with a standard `ErrorDetail` response.
     19   :http:statuscode:`404 Not found`:
     20     The reserve key does not belong to a reserve known to the exchange.
     21   :http:statuscode:`409 Conflict`:
     22     The balance of the reserve or of a coin was insufficient.
     23     Which case it is can be decided by looking at the error code
     24     (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or
     25     ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` or
     26     ``TALER_EC_EXCHANGE_OPEN_INSUFFICIENT_FUNDS``).
     27     The specific fields of the response depend on the error code
     28     and include the signatures (and what was signed over) proving the
     29     conflict.
     30     The response is `WithdrawError` object or a `DepositDoubleSpendError`
     31     depending on the error type.
     32   :http:statuscode:`451 Unavailable For Legal Reasons`:
     33     This account has not yet passed the KYC checks.
     34     The client must pass KYC checks before the reserve can be opened.
     35     The response will be an `LegitimizationNeededResponse` object.
     36 
     37   **Details:**
     38 
     39   .. ts:def:: ReserveOpenRequest
     40 
     41     interface ReserveOpenRequest {
     42       // Signature of purpose
     43       // ``TALER_SIGNATURE_WALLET_RESERVE_OPEN`` over
     44       // a `TALER_ReserveOpenPS`.
     45       reserve_sig: EddsaSignature;
     46 
     47       // Array of payments made towards the cost of the
     48       // operation.
     49       payments: OpenPaymentDetail[];
     50 
     51       // Amount to be paid from the reserve for this
     52       // operation.
     53       reserve_payment: Amount;
     54 
     55       // Time when the client made the request.
     56       // Timestamp must be reasonably close to the time of
     57       // the exchange, otherwise the exchange may reject
     58       // the request (with a status code of 400).
     59       request_timestamp: Timestamp;
     60 
     61       // Desired new expiration time for the reserve.
     62       // If the reserve would expire before this time,
     63       // the exchange will charge account fees (and
     64       // possibly KYC fees) until the expiration time
     65       // exceeds this timestamp. Note that the exchange
     66       // will refuse requests (with a status code of 400)
     67       // if the time is so far in the future that the
     68       // fees are not yet known (see /keys).
     69       reserve_expiration: Timestamp;
     70 
     71       // Desired open purse limit. Can be used to pay the
     72       // annual account fee more than once to get a larger
     73       // purse limit.
     74       purse_limit: Integer;
     75 
     76     }
     77 
     78   .. ts:def:: ReserveOpenResponse
     79 
     80     interface ReserveOpenResponse {
     81       // Transaction cost for extending the expiration time.
     82       // Excludes KYC fees.
     83       open_cost: Amount;
     84 
     85       // Current expiration time for the reserve.
     86       reserve_expiration: Timestamp;
     87     }
     88 
     89   .. ts:def:: ReserveOpenFailure
     90 
     91     interface ReserveOpenFailure {
     92       // Transaction cost that should have been paid
     93       // to extending the reserve as requested.
     94       // Excludes KYC fees.
     95       open_cost: Amount;
     96 
     97       // Remaining expiration time for the reserve.
     98       reserve_expiration: Timestamp;
     99     }
    100 
    101   .. ts:def:: OpenPaymentDetail
    102 
    103     interface OpenPaymentDetail {
    104 
    105       // Contribution of this coin to the overall amount.
    106       // Can be a fraciton of the coin's total value.
    107       amount: Amount;
    108 
    109       // Hash of denomination RSA key with which the coin is signed.
    110       denom_pub_hash: HashCode;
    111 
    112       // Exchange's unblinded RSA signature of the coin.
    113       ub_sig: DenominationSignature;
    114 
    115       // Age commitment for the coin, if the denomination is age-restricted.
    116       age_commitment?: AgeCommitment;
    117 
    118       // Signature over `TALER_ReserveOpenDepositSignaturePS`
    119       // of purpose ``TALER_SIGNATURE_WALLET_RESERVE_OPEN_DEPOSIT``
    120       // made by the customer with the
    121       // `coin's private key <coin-priv>`.
    122       coin_sig: EddsaSignature;
    123 
    124       // Public key of the coin being used to pay for
    125       // opening the reserve.
    126       coin_pub: EddsaPublicKey;
    127 
    128     }