post-purses-PURSE_PUB-deposit.rst (4965B)
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. Which case it is 30 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_PURSE_DEPOSIT_CONFLICTING_META_DATA``). 34 This response comes with a standard `PurseConflict` response 35 (alas some cases are impossible). 36 :http:statuscode:`410 Gone`: 37 The purse has expired, was deleted, or the deposit was already decided. 38 Possible error codes include 39 ``TALER_EC_EXCHANGE_GENERIC_PURSE_EXPIRED``, 40 ``TALER_EC_EXCHANGE_GENERIC_PURSE_DELETED``, or 41 ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_DECIDED_ALREADY``. 42 :http:statuscode:`413 Request entity too large`: 43 The uploaded body is to long, it exceeds the size limit. 44 Returned with an error code of 45 ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``. 46 :http:statuscode:`500 Internal Server Error`: 47 The server experienced an internal error. 48 This response comes with a standard `ErrorDetail` response. 49 Possible error codes include 50 ``TALER_EC_GENERIC_DB_STORE_FAILED``, 51 ``TALER_EC_GENERIC_DB_FETCH_FAILED``, 52 ``TALER_EC_GENERIC_DB_START_FAILED``, or 53 ``TALER_EC_GENERIC_FAILED_COMPUTE_AMOUNT``. 54 55 **Details:** 56 57 .. ts:def:: PurseDeposits 58 59 interface PurseDeposits { 60 61 // Array of coins to deposit into the purse. 62 deposits: PurseDeposit[]; 63 } 64 65 .. ts:def:: PurseDeposit 66 67 interface PurseDeposit { 68 69 // Amount to be deposited, can be a fraction of the 70 // coin's total value. 71 amount: Amount; 72 73 // Hash of denomination RSA key with which the coin is signed. 74 denom_pub_hash: HashCode; 75 76 // Exchange's unblinded RSA signature of the coin. 77 ub_sig: DenominationSignature; 78 79 // Age commitment for the coin, if the denomination is age-restricted. 80 age_commitment?: AgeCommitment; 81 82 // Attestation for the minimum age, if the denomination is age-restricted. 83 attest?: Attestation; 84 85 // Signature over `TALER_PurseDepositSignaturePS` 86 // of purpose ``TALER_SIGNATURE_WALLET_PURSE_DEPOSIT`` 87 // made by the customer with the 88 // `coin's private key <coin-priv>`. 89 coin_sig: EddsaSignature; 90 91 // Public key of the coin being deposited into the purse. 92 coin_pub: EddsaPublicKey; 93 94 } 95 96 .. ts:def:: PurseDepositSuccessResponse 97 98 interface PurseDepositSuccessResponse { 99 100 // Total amount paid into the purse. 101 total_deposited: Amount; 102 103 // Total amount expected in the purse. 104 purse_value_after_fees: Amount; 105 106 // Time at which the deposit came into effect. 107 exchange_timestamp: Timestamp; 108 109 // Indicative time by which the purse should expire 110 // if it has not been merged into an account. At this 111 // point, all of the deposits made will be auto-refunded. 112 purse_expiration: Timestamp; 113 114 // SHA-512 hash of the contact of the purse. 115 h_contract_terms: HashCode; 116 117 // EdDSA signature of the exchange affirming the payment, 118 // of purpose ``TALER_SIGNATURE_PURSE_DEPOSIT_CONFIRMED`` 119 // over a `TALER_PurseDepositConfirmedSignaturePS`. 120 // Signs over the above and the purse public key and 121 // the hash of the contract terms. 122 exchange_sig: EddsaSignature; 123 124 // public key used to create the signature. 125 exchange_pub: EddsaPublicKey; 126 127 } 128 129 .. ts:def:: AgeCommitment 130 131 // AgeCommitment is an array of public keys, one for each age group of the 132 // age-restricted denomination. 133 type AgeCommitment = Edx25519PublicKey[]; 134 135 .. ts:def:: Attestation 136 137 // An attestation for a minimum age is an Edx25519 signature of the age 138 // with purpose ``TALER_SIGNATURE_WALLET_AGE_ATTESTATION``. 139 type Attestation = string;