post-reserves-RESERVE_PUB-purse.rst (4047B)
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``: The requested purse expiration time is in the past. 20 21 :http:statuscode:`402 Payment Required`: 22 The account needs to contain more funding to create more purses. 23 This response comes with a standard `ErrorDetail` response. 24 :http:statuscode:`403 Forbidden`: 25 Account or contract signature is invalid. 26 This response comes with a standard `ErrorDetail` response. 27 :http:statuscode:`404 Not found`: 28 The purse creation operation failed as we could not find the reserve. 29 This response comes with a standard `ErrorDetail` response. 30 :http:statuscode:`409 Conflict`: 31 The purse creation failed because a purse with 32 the same public key but different meta data was 33 created previously. Which specific conflict it is 34 can be decided by looking at the error code 35 (``TALER_EC_EXCHANGE_PURSE_CREATE_CONFLICTING_META_DATA`` or 36 ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA`` or 37 ``TALER_EC_EXCHANGE_PURSE_ECONTRACT_CONFLICTING_META_DATA``). 38 The specific fields of the response depend on the error code 39 and include the signatures (and what was signed over) proving the 40 conflict. 41 The response will be a `PurseConflict` response 42 (but not a `DepositDoubleSpendError`). 43 :http:statuscode:`451 Unavailable For Legal Reasons`: 44 This account has not yet passed the KYC checks. 45 The client must pass KYC checks before proceeding with the merge. 46 The response will be an `LegitimizationNeededResponse` object. 47 48 **Details:** 49 50 .. ts:def:: ReservePurseRequest 51 52 interface ReservePurseRequest { 53 54 // Minimum amount that must be credited to the reserve, that is 55 // the total value of the purse minus the deposit fees. 56 // If the deposit fees are lower, the contribution to the 57 // reserve can be higher! 58 purse_value: Amount; 59 60 // Minimum age required for all coins deposited into the purse. 61 min_age: Integer; 62 63 // Purse fee the reserve owner is willing to pay 64 // for the purse creation. Optional, if not present 65 // the purse is to be created from the purse quota 66 // of the reserve. 67 purse_fee: Amount; 68 69 // Optional encrypted contract, in case the buyer is 70 // proposing the contract and thus establishing the 71 // purse with the payment. 72 econtract?: EncryptedContract; 73 74 // EdDSA public key used to approve merges of this purse. 75 merge_pub: EddsaPublicKey; 76 77 // EdDSA signature of the purse private key affirming the merge 78 // over a `TALER_PurseMergeSignaturePS`. 79 // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``. 80 merge_sig: EddsaSignature; 81 82 // EdDSA signature of the account/reserve affirming the merge. 83 // Must be of purpose ``TALER_SIGNATURE_WALLET_ACCOUNT_MERGE`` 84 reserve_sig: EddsaSignature; 85 86 // Purse public key. 87 purse_pub: EddsaPublicKey; 88 89 // EdDSA signature of the purse over 90 // `TALER_PurseRequestSignaturePS` of 91 // purpose ``TALER_SIGNATURE_PURSE_REQUEST`` 92 // confirming that the 93 // above details hold for this purse. 94 purse_sig: EddsaSignature; 95 96 // SHA-512 hash of the contact of the purse. 97 h_contract_terms: HashCode; 98 99 // Client-side timestamp of when the merge request was made. 100 merge_timestamp: Timestamp; 101 102 // Indicative time by which the purse should expire 103 // if it has not been paid. 104 purse_expiration: Timestamp; 105 106 }