post-purses-PURSE_PUB-deposit.rst (5044B)
1 .. http:post:: /purses/$PURSE_PUB/deposit 2 3 Deposit money into a purse. Used by the buyer for a PULL payment. 4 5 **Request:** 6 7 The request body must be a `PurseDeposits` object. 8 9 **Response:** 10 11 :http:statuscode:`200 OK`: 12 The operation succeeded, the exchange confirms that all 13 coins were deposited into the purse. 14 The response will include a `PurseDepositSuccessResponse` object. 15 :http:statuscode:`400 Bad Request`: 16 The request body is malformed or a parameter is invalid. 17 This response comes with a standard `ErrorDetail` response with 18 a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. 19 :http:statuscode:`403 Forbidden`: 20 A coin or denomination signature is invalid. 21 This response comes with a standard `ErrorDetail` response. 22 :http:statuscode:`404 Not found`: 23 The purse is unknown. 24 This response comes with a standard `ErrorDetail` response with 25 a code of ``TALER_EC_EXCHANGE_GENERIC_PURSE_UNKNOWN``. 26 :http:statuscode:`409 Conflict`: 27 The deposit operation has either failed because a coin has insufficient 28 residual value, or because the same public key of the coin has been 29 previously used with a different denomination or age commitment. 30 Which case it is can be decided by looking at the error code 31 (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or 32 ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` or 33 ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_AGE_HASH`` or 34 ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA``). 35 This response comes with a standard `PurseConflict` response 36 (alas some cases are impossible). 37 :http:statuscode:`410 Gone`: 38 The purse has expired, was deleted, or the deposit was already decided. 39 Possible error codes include 40 ``TALER_EC_EXCHANGE_GENERIC_PURSE_EXPIRED``, 41 ``TALER_EC_EXCHANGE_GENERIC_PURSE_DELETED``, or 42 ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_DECIDED_ALREADY``. 43 :http:statuscode:`413 Request entity too large`: 44 The uploaded body is to long, it exceeds the size limit. 45 Returned with an error code of 46 ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``. 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_STORE_FAILED``, 52 ``TALER_EC_GENERIC_DB_FETCH_FAILED``, 53 ``TALER_EC_GENERIC_DB_START_FAILED``, or 54 ``TALER_EC_GENERIC_FAILED_COMPUTE_AMOUNT``. 55 56 **Details:** 57 58 .. ts:def:: PurseDeposits 59 60 interface PurseDeposits { 61 62 // Array of coins to deposit into the purse. 63 deposits: PurseDeposit[]; 64 } 65 66 .. ts:def:: PurseDeposit 67 68 interface PurseDeposit { 69 70 // Amount to be deposited, can be a fraction of the 71 // coin's total value. 72 amount: Amount; 73 74 // Hash of denomination RSA key with which the coin is signed. 75 denom_pub_hash: HashCode; 76 77 // Exchange's unblinded RSA signature of the coin. 78 ub_sig: DenominationSignature; 79 80 // Age commitment for the coin, if the denomination is age-restricted. 81 age_commitment?: AgeCommitment; 82 83 // Attestation for the minimum age, if the denomination is age-restricted. 84 attest?: Attestation; 85 86 // Signature over `TALER_PurseDepositSignaturePS` 87 // of purpose ``TALER_SIGNATURE_WALLET_PURSE_DEPOSIT`` 88 // made by the customer with the 89 // `coin's private key <coin-priv>`. 90 coin_sig: EddsaSignature; 91 92 // Public key of the coin being deposited into the purse. 93 coin_pub: EddsaPublicKey; 94 95 } 96 97 .. ts:def:: PurseDepositSuccessResponse 98 99 interface PurseDepositSuccessResponse { 100 101 // Total amount paid into the purse. 102 total_deposited: Amount; 103 104 // Total amount expected in the purse. 105 purse_value_after_fees: Amount; 106 107 // Time at which the deposit came into effect. 108 exchange_timestamp: Timestamp; 109 110 // Indicative time by which the purse should expire 111 // if it has not been merged into an account. At this 112 // point, all of the deposits made will be auto-refunded. 113 purse_expiration: Timestamp; 114 115 // SHA-512 hash of the contact of the purse. 116 h_contract_terms: HashCode; 117 118 // EdDSA signature of the exchange affirming the payment, 119 // of purpose ``TALER_SIGNATURE_PURSE_DEPOSIT_CONFIRMED`` 120 // over a `TALER_PurseDepositConfirmedSignaturePS`. 121 // Signs over the above and the purse public key and 122 // the hash of the contract terms. 123 exchange_sig: EddsaSignature; 124 125 // public key used to create the signature. 126 exchange_pub: EddsaPublicKey; 127 128 } 129 130 .. ts:def:: AgeCommitment 131 132 // AgeCommitment is an array of public keys, one for each age group of the 133 // age-restricted denomination. 134 type AgeCommitment = Edx25519PublicKey[]; 135 136 .. ts:def:: Attestation 137 138 // An attestation for a minimum age is an Edx25519 signature of the age 139 // with purpose ``TALER_SIGNATURE_WALLET_AGE_ATTESTATION``. 140 type Attestation = string;