taler-docs

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

post-reserves-RESERVE_PUB-close.rst (3672B)

      1 .. http:post:: /reserves/$RESERVE_PUB/close
      2 
      3   Force immediate closure of a reserve. Does not actually
      4   delete the reserve or the KYC data, but merely forces
      5   the reserve's current balance to be wired back to the
      6   account where it originated from, or another account of
      7   the user's choosing if they performed the required KYC
      8   check and designated another target account.
      9 
     10   **Request:**
     11 
     12   The request body must be a `ReserveCloseRequest` object.
     13 
     14   **Response:**
     15 
     16   :http:statuscode:`200 OK`:
     17     The exchange responds with a `ReserveCloseResponse` object. Note
     18     that if the reserve balance is less than the closing fee, the
     19     server will just return an amount of zero and simply not wire any
     20     funds.
     21   :http:statuscode:`400 Bad Request`:
     22     The request timestamp has excessive clock skew.
     23     This response comes with a standard `ErrorDetail` response with
     24     a code of ``TALER_EC_EXCHANGE_GENERIC_CLOCK_SKEW``.
     25   :http:statuscode:`403 Forbidden`:
     26     The *TALER_SIGNATURE_WALLET_RESERVE_CLOSE* signature is invalid.
     27     This response comes with a standard `ErrorDetail` response with
     28     a code of ``TALER_EC_EXCHANGE_RESERVES_CLOSE_BAD_SIGNATURE``.
     29   :http:statuscode:`404 Not found`:
     30     The reserve key does not belong to a reserve known to the exchange.
     31     This response comes with a standard `ErrorDetail` response with
     32     a code of ``TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN``.
     33   :http:statuscode:`409 Conflict`:
     34     No target account was given, and the exchange does not know an
     35     origin account for this reserve.
     36     This response comes with a standard `ErrorDetail` response with
     37     a code of ``TALER_EC_EXCHANGE_RESERVES_CLOSE_NO_TARGET_ACCOUNT``.
     38   :http:statuscode:`413 Request entity too large`:
     39     The uploaded body is to long, it exceeds the size limit.
     40     Returned with an error code of
     41     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     42   :http:statuscode:`451 Unavailable For Legal Reasons`:
     43     This account has not yet passed the KYC checks, hence wiring
     44     funds to a non-origin account is not allowed.
     45     The client must pass KYC checks before the reserve can be opened.
     46     The response will be an `LegitimizationNeededResponse` object.
     47   :http:statuscode:`500 Internal Server Error`:
     48     The server experienced an internal error.
     49     This response comes with a standard `ErrorDetail` response.
     50     Possible error codes include
     51     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     52     ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``, or
     53     ``TALER_EC_EXCHANGE_WIRE_FEES_NOT_CONFIGURED``.
     54 
     55   **Details:**
     56 
     57   .. ts:def:: ReserveCloseRequest
     58 
     59     interface ReserveCloseRequest {
     60       // Signature of purpose
     61       // ``TALER_SIGNATURE_WALLET_RESERVE_CLOSE`` over
     62       // a `TALER_ReserveCloseRequestSignaturePS`.
     63       reserve_sig: EddsaSignature;
     64 
     65       // Time when the client made the request.
     66       // Timestamp must be reasonably close to the time of
     67       // the exchange, otherwise the exchange may reject
     68       // the request (with a status code of 400).
     69       request_timestamp: Timestamp;
     70 
     71       // Full payto://-URI of the account the reserve balance is to be
     72       // wired to.  Must be of the form: 'payto://$METHOD' for a
     73       // wire method supported by this exchange (if the
     74       // method is not supported, this is a bad request (400)).
     75       // If not given, the reserve's origin account
     76       // will be used. If no origin account is known for the
     77       // reserve and not given, this is a conflict (409).
     78       payto_uri?: string;
     79 
     80     }
     81 
     82   .. ts:def:: ReserveCloseResponse
     83 
     84     interface ReserveCloseResponse {
     85 
     86       // Actual amount that will be wired (excludes closing fee).
     87       wire_amount: Amount;
     88 
     89     }