taler-docs

post-reserves-RESERVE_PUB-purse.rst (6335B)

---

 .. http:post:: /reserves/$RESERVE_PUB/purse
 
   Create purse for an account.  First step of a PULL payment.
 
   **Request:**
 
   The request body must be a `ReservePurseRequest` object.
 
   A purse that is not paid in full refunds the coins that were deposited
   into it when it expires, and the exchange must still be able to account
   for that refund.  ``purse_expiration`` is therefore limited to
   ``max_p2p_expiration`` (see :http:get:`/keys </keys>`) from now.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The operation succeeded, the exchange confirms that the
     purse was allocated.
     The response will include a `PurseCreateSuccessResponse` object.
   :http:statuscode:`400 Bad Request`:
     The request is invalid.  In addition to generic error codes,
     the following specific error codes may be returned:
 
     1. ``TALER_EC_EXCHANGE_RESERVES_PURSE_EXPIRATION_BEFORE_NOW``:
        The requested purse expiration time is in the past.
     2. ``TALER_EC_EXCHANGE_RESERVES_PURSE_CREATE_INSUFFICIENT_FUNDS``:
        The reserve does not have enough funds to create this reserve.
     3. ``TALER_EC_EXCHANGE_RESERVES_PURSE_EXPIRATION_IS_NEVER``:
        A purse expiration time of "never" is not allowed.
     4. ``TALER_EC_EXCHANGE_RESERVES_PURSE_FEE_TOO_LOW``:
        The specified purse fee is lower than allowed.
     5. ``TALER_EC_EXCHANGE_RESERVES_PURSE_EXPIRATION_TOO_LATE``:
        The requested purse expiration time is further in the future than
        ``max_p2p_expiration`` allows.  The ``detail`` of the `ErrorDetail`
        gives the latest purse expiration the exchange accepts.
 
   :http:statuscode:`403 Forbidden`:
     Account or contract signature is invalid.
     This response comes with a standard `ErrorDetail` response.
     Returned with error codes of:
     - ``TALER_EC_EXCHANGE_PURSE_CREATE_SIGNATURE_INVALID``
     - ``TALER_EC_EXCHANGE_PURSE_ECONTRACT_SIGNATURE_INVALID``
     - ``TALER_EC_EXCHANGE_RESERVES_PURSE_MERGE_SIGNATURE_INVALID``
     - ``TALER_EC_EXCHANGE_RESERVES_RESERVE_MERGE_SIGNATURE_INVALID``
 
   :http:statuscode:`404 Not found`:
     The purse creation operation failed as we could not find the reserve.
     This response comes with a standard `ErrorDetail` response.
     Returned with an EC of ``TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN``
   :http:statuscode:`409 Conflict`:
     The purse creation failed because a purse with
     the same public key but different meta data was
     created previously or the funds for the operation
     were insufficient.  Which specific conflict it is
     can be decided by looking at the error code:
     - ``TALER_EC_EXCHANGE_PURSE_CREATE_CONFLICTING_META_DATA``
     - ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA``
     - ``TALER_EC_EXCHANGE_PURSE_ECONTRACT_CONFLICTING_META_DATA``
     - ``TALER_EC_EXCHANGE_RESERVES_PURSE_CREATE_INSUFFICIENT_FUNDS``
     - ``TALER_EC_EXCHANGE_RESERVES_PURSE_CREATE_CONFLICTING_META_DATA``
     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 will be a `PurseConflict` response
     (but not a `DepositDoubleSpendError`).
   :http:statuscode:`410 Gone`:
     The purse has expired.
     This response comes with a standard `ErrorDetail` response with
     a code of ``TALER_EC_EXCHANGE_GENERIC_PURSE_EXPIRED``.
   :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:`451 Unavailable For Legal Reasons`:
     This account has not yet passed the KYC checks.
     The client must pass KYC checks before proceeding with the merge.
     The response will be an `LegitimizationNeededResponse` object.
   :http:statuscode:`500 Internal Server Error`:
     The server experienced an internal error.
     This response comes with a standard `ErrorDetail` response.
     Possible error codes include
     ``TALER_EC_GENERIC_DB_STORE_FAILED``,
     ``TALER_EC_GENERIC_DB_FETCH_FAILED``, or
     ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``.
   :http:statuscode:`503 Service unavailable`:
     The server could not process the request because it is currently
     unavailable. Error codes include:
     - ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING``
     - ``TALER_EC_EXCHANGE_GENERIC_GLOBAL_FEES_MISSING``
 
   **Details:**
 
   .. ts:def:: ReservePurseRequest
 
     interface ReservePurseRequest {
 
       // Minimum amount that must be credited to the reserve, that is
       // the total value of the purse minus the deposit fees.
       // If the deposit fees are lower, the contribution to the
       // reserve can be higher!
       purse_value: Amount;
 
       // Minimum age required for all coins deposited into the purse.
       min_age: Integer;
 
       // Purse fee the reserve owner is willing to pay
       // for the purse creation. Optional, if not present
       // the purse is to be created from the purse quota
       // of the reserve.
       purse_fee?: Amount;
 
       // Optional encrypted contract, in case the buyer is
       // proposing the contract and thus establishing the
       // purse with the payment.
       econtract?: EncryptedContract;
 
       // EdDSA public key used to approve merges of this purse.
       merge_pub: EddsaPublicKey;
 
       // EdDSA signature of the purse private key affirming the merge
       // over a `TALER_PurseMergeSignaturePS`.
       // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``.
       merge_sig: EddsaSignature;
 
       // EdDSA signature of the account/reserve affirming the merge.
       // Must be of purpose ``TALER_SIGNATURE_WALLET_ACCOUNT_MERGE``
       reserve_sig: EddsaSignature;
 
       // Purse public key.
       purse_pub: EddsaPublicKey;
 
       // EdDSA signature of the purse over
       // `TALER_PurseRequestSignaturePS` of
       // purpose ``TALER_SIGNATURE_PURSE_REQUEST``
       // confirming that the
       // above details hold for this purse.
       purse_sig: EddsaSignature;
 
       // SHA-512 hash of the contact of the purse.
       h_contract_terms: HashCode;
 
       // Client-side timestamp of when the merge request was made.
       merge_timestamp: Timestamp;
 
       // Indicative time by which the purse should expire
       // if it has not been paid.
       purse_expiration: Timestamp;
 
     }