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