post-batch-deposit.rst (9793B)
1 .. http:post:: /batch-deposit 2 3 Deposit multiple coins and ask the exchange to transfer the given :ref:`amount` 4 into the merchant's bank account. This API is used by the merchant to redeem 5 the digital coins. 6 7 **Request:** 8 9 The request body must be a `BatchDepositRequest` object. 10 11 **Response:** 12 13 :http:statuscode:`200 OK`: 14 The operation succeeded, the exchange confirms that no double-spending took 15 place. The response will be a `DepositSuccessResponse` object. 16 :http:statuscode:`400 Bad Request`: 17 The request is malformed or a parameter is invalid. 18 This response comes with a standard `ErrorDetail` response. 19 Possible error codes include ``TALER_EC_GENERIC_PARAMETER_MALFORMED``, 20 ``TALER_EC_EXCHANGE_DEPOSIT_NEGATIVE_VALUE_AFTER_FEE``, 21 ``TALER_EC_EXCHANGE_DEPOSIT_REFUND_DEADLINE_AFTER_WIRE_DEADLINE``, 22 ``TALER_EC_EXCHANGE_DEPOSIT_WIRE_DEADLINE_IS_NEVER``, 23 ``TALER_EC_EXCHANGE_GENERIC_AMOUNT_EXCEEDS_DENOMINATION_VALUE``, 24 ``TALER_EC_EXCHANGE_GENERIC_CIPHER_MISMATCH``, or 25 ``TALER_EC_EXCHANGE_DEPOSITS_POLICY_NOT_ACCEPTED``. 26 :http:statuscode:`403 Forbidden`: 27 One of the signatures is invalid. 28 This response comes with a standard `ErrorDetail` response. 29 Possible error codes include 30 ``TALER_EC_EXCHANGE_DEPOSIT_COIN_SIGNATURE_INVALID`` or 31 ``TALER_EC_EXCHANGE_DENOMINATION_SIGNATURE_INVALID``. 32 :http:statuscode:`404 Not found`: 33 Either one of the denomination keys is not recognized (expired or invalid), 34 or the wire type is not recognized. 35 If a denomination key is unknown, the response will be 36 a `DenominationUnknownMessage`. 37 :http:statuscode:`409 Conflict`: 38 The deposit operation has either failed because a coin has insufficient 39 residual value, or because the same public key of a coin has been 40 previously used with a different denomination. 41 Which case it is can be decided by looking at the error code: 42 43 1. ``TALER_EC_EXCHANGE_DEPOSIT_CONFLICTING_CONTRACT`` (same coin used in different ways), 44 2. ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` (balance insufficient), 45 3. ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` (same coin public key, but different denomination). 46 4. ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_AGE_HASH`` (same coin public key, but different age commitment). 47 48 The response is a `DepositDoubleSpendError` for cases 1 and 2, a 49 `CoinDenominationConflictError` for case 3 and a 50 `CoinAgeCommitmentConflictError` for case 4. 51 The request should not be repeated again with this coin. Instead, the client 52 can get from the exchange via the ``/coin/$COIN_PUB/history`` endpoint the record 53 of the transactions known for this coin's public key. 54 :http:statuscode:`410 Gone`: 55 The requested denomination key is no longer valid. 56 It is past the expiration or was revoked. The response is a 57 `DenominationGoneMessage`. Clients must evaluate 58 the error code provided to understand which of the 59 cases this is and handle it accordingly. 60 Possible error codes include 61 ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED`` or 62 ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_REVOKED``. 63 :http:statuscode:`412 Precondition Failed`: 64 The requested denomination key is not yet valid. 65 It is before the validity start time. The response is a 66 `DenominationGoneMessage` with 67 ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE``. 68 :http:statuscode:`413 Request entity too large`: 69 The uploaded body is to long, it exceeds the size limit. 70 Returned with an error code of 71 ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``. 72 :http:statuscode:`451 Unavailable For Legal Reasons`: 73 This merchant has not yet passed the KYC checks. 74 The client must pass KYC checks before proceeding with the deposit. 75 The response will be an `LegitimizationNeededResponse` object. 76 @since protocol **v21**. 77 :http:statuscode:`500 Internal Server Error`: 78 The server experienced an internal error. 79 This response comes with a standard `ErrorDetail` response. 80 Possible error codes include 81 ``TALER_EC_GENERIC_DB_STORE_FAILED``, 82 ``TALER_EC_GENERIC_DB_START_FAILED``, or 83 ``TALER_EC_GENERIC_DB_FETCH_FAILED``. 84 85 **Details:** 86 87 .. ts:def:: BatchDepositRequest 88 89 interface BatchDepositRequest { 90 91 // The merchant's account details as a full payto URI. 92 merchant_payto_uri: string; 93 94 // The salt is used to hide the ``payto_uri`` from customers 95 // when computing the ``h_wire`` of the merchant. 96 wire_salt: WireSalt; 97 98 // SHA-512 hash of the contract of the merchant with the customer. Further 99 // details are never disclosed to the exchange. 100 h_contract_terms: HashCode; 101 102 // Merchant's signature over the h_contract_terms. 103 // @since protocol **v22** 104 merchant_sig: EddsaSignature; 105 106 // The list of coins that are going to be deposited with this Request. 107 coins: BatchDepositRequestCoin[]; 108 109 // Timestamp when the contract was finalized. 110 timestamp: Timestamp; 111 112 // Indicative time by which the exchange undertakes to transfer the funds to 113 // the merchant, in case of successful payment. A wire transfer deadline of 'never' 114 // is not allowed. 115 wire_transfer_deadline: Timestamp; 116 117 // EdDSA `public key of the merchant <merchant-pub>`, so that the client can identify the 118 // merchant for refund requests. 119 merchant_pub: EddsaPublicKey; 120 121 // Additional text to include in the wire transfer subject when 122 // settling the payment. Note that the merchant MUST use this 123 // consistently for the same ``merchant_pub`` and ``merchant_payto_uri`` 124 // as during aggregation *any* of these values may be selected 125 // for the actual aggregated wire transfer. If a merchant wants 126 // to use different ``extra_subject`` values for the same IBAN, 127 // it should thus create multiple instances (with different 128 // ``merchant_pub`` values). When changing the ``extra_subject``, 129 // the change may thus not be immediately reflected in the 130 // settlements. 131 // 132 // Must match [a-zA-Z0-9-.:]{1, 40} 133 // 134 // Optional. Since **v32**. 135 extra_wire_subject_metadata?: string; 136 137 // Date until which the merchant can issue a refund to the customer via the 138 // exchange, to be omitted if refunds are not allowed. 139 refund_deadline?: Timestamp; 140 } 141 142 .. ts:def:: BatchDepositRequestCoin 143 144 interface BatchDepositRequestCoin { 145 // EdDSA public key of the coin being deposited. 146 coin_pub: EddsaPublicKey; 147 148 // Hash of denomination RSA key with which the coin is signed. 149 denom_pub_hash: HashCode; 150 151 // Exchange's unblinded RSA signature of the coin. 152 ub_sig: DenominationSignature; 153 154 // Amount to be deposited, can be a fraction of the 155 // coin's total value. 156 contribution: Amount; 157 158 // Signature over `TALER_DepositRequestPS`, made by the customer with the 159 // `coin's private key <coin-priv>`. 160 coin_sig: EddsaSignature; 161 162 // Hash over the age commitment of the coin. 163 // Only present if the coin is actually age-restricted. 164 h_age_commitment?: HashCode; 165 } 166 167 .. ts:def:: DenominationSignature 168 169 type DenominationSignature = DenomCipher & ( 170 | RsaDenominationSignature 171 | CSDenominationSignature 172 ); 173 174 .. ts:def:: RsaDenominationSignature 175 176 interface RsaDenominationSignature extends DenomCipher { 177 cipher: "RSA"; 178 179 // RSA signature 180 rsa_signature: RsaSignature; 181 } 182 183 .. ts:def:: CSDenominationSignature 184 185 interface CSDenominationSignature extends DenomCipher { 186 cipher: "CS"; 187 188 // R value component of the signature. 189 cs_signature_r: Cs25519Point; 190 191 // s value component of the signature. 192 cs_signature_s: Cs25519Scalar; 193 194 } 195 196 The deposit operation succeeds if the coin is valid for making a deposit and 197 has enough residual value that has not already been deposited or melted. 198 199 .. ts:def:: DepositSuccessResponse 200 201 interface DepositSuccessResponse { 202 203 // Total amount deposited so far under this contract terms for 204 // this merchant. 205 // Since **v33**. 206 accumulated_total_without_fee: Amount; 207 208 // Timestamp when the deposit was received by the exchange. 209 exchange_timestamp: Timestamp; 210 211 // `Public EdDSA key of the exchange <sign-key-pub>` that was used to 212 // generate the signature. 213 // Should match one of the exchange's signing keys from ``/keys``. It is given 214 // explicitly as the client might otherwise be confused by clock skew as to 215 // which signing key was used. 216 exchange_pub: EddsaPublicKey; 217 218 // Deposit confirmation signature from the exchange. 219 // The EdDSA signature of `TALER_DepositConfirmationPS` using a current 220 // `signing key of the exchange <sign-key-priv>` affirming the successful 221 // deposit and that the exchange will transfer the funds after the refund 222 // deadline, or as soon as possible if the refund deadline is zero. 223 exchange_sig: EddsaSignature; 224 } 225 226 .. ts:def:: DepositDoubleSpendError 227 228 interface DepositDoubleSpendError { 229 230 // Must be TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS 231 // or TALER_EC_EXCHANGE_DEPOSIT_CONFLICTING_CONTRACT. 232 // (Since **vCONFLICT**, a conflicting denomination is 233 // reported with a `CoinDenominationConflictError` instead.) 234 code: Integer; 235 236 // A string explaining that the user tried to 237 // double-spend. 238 hint: string; 239 240 // EdDSA public key of a coin being double-spent. 241 coin_pub: EddsaPublicKey; 242 243 // Hash of the public key of the denomination of the coin. 244 h_denom_pub: HashCode; 245 246 }