post-reserves-RESERVE_PUB-purse.rst (5779B)
1 .. http:post:: /reserves/$RESERVE_PUB/purse 2 3 Create purse for an account. First step of a PULL payment. 4 5 **Request:** 6 7 The request body must be a `ReservePurseRequest` object. 8 9 **Response:** 10 11 :http:statuscode:`200 OK`: 12 The operation succeeded, the exchange confirms that the 13 purse was allocated. 14 The response will include a `PurseCreateSuccessResponse` object. 15 :http:statuscode:`400 Bad Request`: 16 The request is invalid. In addition to generic error codes, 17 the following specific error codes may be returned: 18 19 1. ``TALER_EC_EXCHANGE_RESERVES_PURSE_EXPIRATION_BEFORE_NOW``: 20 The requested purse expiration time is in the past. 21 2. ``TALER_EC_EXCHANGE_RESERVES_PURSE_CREATE_INSUFFICIENT_FUNDS``: 22 The reserve does not have enough funds to create this reserve. 23 3. ``TALER_EC_EXCHANGE_RESERVES_PURSE_EXPIRATION_IS_NEVER``: 24 A purse expiration time of "never" is not allowed. 25 4. ``TALER_EC_EXCHANGE_RESERVES_PURSE_FEE_TOO_LOW``: 26 The specified purse fee is lower than allowed. 27 28 :http:statuscode:`403 Forbidden`: 29 Account or contract signature is invalid. 30 This response comes with a standard `ErrorDetail` response. 31 Returned with error codes of: 32 - ``TALER_EC_EXCHANGE_PURSE_CREATE_SIGNATURE_INVALID`` 33 - ``TALER_EC_EXCHANGE_PURSE_ECONTRACT_SIGNATURE_INVALID`` 34 - ``TALER_EC_EXCHANGE_RESERVES_PURSE_MERGE_SIGNATURE_INVALID`` 35 - ``TALER_EC_EXCHANGE_RESERVES_RESERVE_MERGE_SIGNATURE_INVALID`` 36 37 :http:statuscode:`404 Not found`: 38 The purse creation operation failed as we could not find the reserve. 39 This response comes with a standard `ErrorDetail` response. 40 Returned with an EC of ``TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN`` 41 :http:statuscode:`409 Conflict`: 42 The purse creation failed because a purse with 43 the same public key but different meta data was 44 created previously or the funds for the operation 45 were insufficient. Which specific conflict it is 46 can be decided by looking at the error code: 47 - ``TALER_EC_EXCHANGE_PURSE_CREATE_CONFLICTING_META_DATA`` 48 - ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA`` 49 - ``TALER_EC_EXCHANGE_PURSE_ECONTRACT_CONFLICTING_META_DATA`` 50 - ``TALER_EC_EXCHANGE_RESERVES_PURSE_CREATE_INSUFFICIENT_FUNDS`` 51 - ``TALER_EC_EXCHANGE_RESERVES_PURSE_CREATE_CONFLICTING_META_DATA`` 52 The specific fields of the response depend on the error code 53 and include the signatures (and what was signed over) proving the 54 conflict. 55 The response will be a `PurseConflict` response 56 (but not a `DepositDoubleSpendError`). 57 :http:statuscode:`410 Gone`: 58 The purse has expired. 59 This response comes with a standard `ErrorDetail` response with 60 a code of ``TALER_EC_EXCHANGE_GENERIC_PURSE_EXPIRED``. 61 :http:statuscode:`413 Request entity too large`: 62 The uploaded body is to long, it exceeds the size limit. 63 Returned with an error code of 64 ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``. 65 :http:statuscode:`451 Unavailable For Legal Reasons`: 66 This account has not yet passed the KYC checks. 67 The client must pass KYC checks before proceeding with the merge. 68 The response will be an `LegitimizationNeededResponse` object. 69 :http:statuscode:`500 Internal Server Error`: 70 The server experienced an internal error. 71 This response comes with a standard `ErrorDetail` response. 72 Possible error codes include 73 ``TALER_EC_GENERIC_DB_STORE_FAILED``, 74 ``TALER_EC_GENERIC_DB_FETCH_FAILED``, or 75 ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``. 76 :http:statuscode:`503 Service unavailable`: 77 The server could not process the request because it is currently 78 unavailable. Error codes include: 79 - ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING`` 80 - ``TALER_EC_EXCHANGE_GENERIC_GLOBAL_FEES_MISSING`` 81 82 **Details:** 83 84 .. ts:def:: ReservePurseRequest 85 86 interface ReservePurseRequest { 87 88 // Minimum amount that must be credited to the reserve, that is 89 // the total value of the purse minus the deposit fees. 90 // If the deposit fees are lower, the contribution to the 91 // reserve can be higher! 92 purse_value: Amount; 93 94 // Minimum age required for all coins deposited into the purse. 95 min_age: Integer; 96 97 // Purse fee the reserve owner is willing to pay 98 // for the purse creation. Optional, if not present 99 // the purse is to be created from the purse quota 100 // of the reserve. 101 purse_fee?: Amount; 102 103 // Optional encrypted contract, in case the buyer is 104 // proposing the contract and thus establishing the 105 // purse with the payment. 106 econtract?: EncryptedContract; 107 108 // EdDSA public key used to approve merges of this purse. 109 merge_pub: EddsaPublicKey; 110 111 // EdDSA signature of the purse private key affirming the merge 112 // over a `TALER_PurseMergeSignaturePS`. 113 // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``. 114 merge_sig: EddsaSignature; 115 116 // EdDSA signature of the account/reserve affirming the merge. 117 // Must be of purpose ``TALER_SIGNATURE_WALLET_ACCOUNT_MERGE`` 118 reserve_sig: EddsaSignature; 119 120 // Purse public key. 121 purse_pub: EddsaPublicKey; 122 123 // EdDSA signature of the purse over 124 // `TALER_PurseRequestSignaturePS` of 125 // purpose ``TALER_SIGNATURE_PURSE_REQUEST`` 126 // confirming that the 127 // above details hold for this purse. 128 purse_sig: EddsaSignature; 129 130 // SHA-512 hash of the contact of the purse. 131 h_contract_terms: HashCode; 132 133 // Client-side timestamp of when the merge request was made. 134 merge_timestamp: Timestamp; 135 136 // Indicative time by which the purse should expire 137 // if it has not been paid. 138 purse_expiration: Timestamp; 139 140 }