taler-docs

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

get-purses-PURSE_PUB-merge.rst (3081B)

      1 .. http:get:: /purses/$PURSE_PUB/merge
      2 .. http:get:: /purses/$PURSE_PUB/deposit
      3 
      4   Obtain information about a purse.  Depending on the suffix,
      5   the long-polling (if any) will wait for either a merge or
      6   a deposit event.
      7 
      8   **Request:**
      9 
     10   :query timeout_ms=NUMBER: *Optional.*  If specified,
     11     the exchange
     12     will wait up to ``NUMBER`` milliseconds for completion
     13     of a merge operation before sending the HTTP response.
     14   :query deposit_timeout_ms=NUMBER: *Optional.*  If specified,
     15     the exchange
     16     will wait up to ``NUMBER`` milliseconds for completion
     17     of a deposit operation before sending the HTTP response.
     18 
     19   **Response:**
     20 
     21   :http:statuscode:`200 OK`:
     22     The operation succeeded, the exchange provides details
     23     about the purse.
     24     The response will include a `PurseStatus` object.
     25   :http:statuscode:`400 Bad Request`:
     26     The request is malformed.
     27     This response comes with a standard `ErrorDetail` response.
     28     Possible error codes include
     29     ``TALER_EC_EXCHANGE_GENERIC_PURSE_PUB_MALFORMED`` or
     30     ``TALER_EC_EXCHANGE_PURSES_INVALID_WAIT_TARGET``.
     31   :http:statuscode:`404 Not found`:
     32     The purse is unknown to the exchange.
     33     This response comes with a standard `ErrorDetail` response with
     34     a code of ``TALER_EC_EXCHANGE_GENERIC_PURSE_UNKNOWN``.
     35   :http:statuscode:`410 Gone`:
     36     The purse expired before the deposit or merge was completed.
     37   :http:statuscode:`500 Internal Server Error`:
     38     The server experienced an internal error.
     39     This response comes with a standard `ErrorDetail` response with
     40     a code of ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
     41 
     42   **Details:**
     43 
     44   .. ts:def:: PurseStatus
     45 
     46      interface PurseStatus {
     47 
     48       // Total amount deposited into the purse so far.
     49       // If 'total_deposit_amount' minus 'deposit_fees'
     50       // exceeds 'merge_value_after_fees', and a
     51       // 'merge_request' exists for the purse, then the
     52       // purse will (have been) merged with the account.
     53       balance: Amount;
     54 
     55       // Time of the merge, missing if "never".
     56       merge_timestamp?: Timestamp;
     57 
     58       // Time of the deposits being complete, missing if "never".
     59       // Note that this time may not be "stable": once sufficient
     60       // deposits have been made, is "now" before the purse
     61       // expiration, and otherwise set to the purse expiration.
     62       // However, this should also not be relied upon. The key
     63       // property is that it is either "never" or in the past.
     64       deposit_timestamp?: Timestamp;
     65 
     66       // Time when the purse expires and
     67       // funds that were not merged are refunded
     68       // on the deposited coins.
     69       // FIXME: Document the exchange protocol version
     70       //        in which this field became available.
     71       purse_expiration: Timestamp;
     72 
     73       // EdDSA signature of the exchange over a
     74       // `TALER_PurseStatusResponseSignaturePS`
     75       // with purpose ``TALER_SIGNATURE_PURSE_STATUS_RESPONSE``
     76       // affirming the purse status.
     77       exchange_sig: EddsaSignature;
     78 
     79       // EdDSA public key exchange used for 'exchange_sig'.
     80       exchange_pub: EddsaPublicKey;
     81 
     82     }