-specify batch-deposit endpoint

1 files changed, 141 insertions, 0 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 0a18335c..1223086d 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -2441,6 +2441,147 @@ denomination.
     }
 
 
+.. http:POST:: /batch-deposit
+
+  Deposit multiple coins and ask the exchange to transfer the given :ref:`amount`
+  into the merchant's bank account.  This API is used by the merchant to redeem
+  the digital coins.
+
+  **Request:**
+
+  The request body must be a `BatchDepositRequest` object.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The operation succeeded, the exchange confirms that no double-spending took
+    place.  The response will include a `BatchDepositSuccess` object.
+  :http:statuscode:`403 Forbidden`:
+    One of the signatures is invalid.
+    This response comes with a standard `ErrorDetail` response.
+  :http:statuscode:`404 Not found`:
+    Either one of the denomination keys is not recognized (expired or invalid),
+    or the wire type is not recognized.
+    If a denomination key is unknown, the response will be
+    a `DenominationUnknownMessage`.
+  :http:statuscode:`409 Conflict`:
+    The deposit operation has either failed because a coin has insufficient
+    residual value, or because the same public key of a coin has been
+    previously used with a different denomination.  Which case it is
+    can be decided by looking at the error code
+    (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or
+    ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``).
+    The fields of the response are the same in both cases.
+    The request should not be repeated again with this coin.
+    In this case, the response is a `DepositDoubleSpendError` with
+    an additional `coin_pub` field specifying the public key of the
+    coin that was double-spent.
+  :http:statuscode:`410 Gone`:
+    The requested denomination key is not yet or no longer valid.
+    It either before the validity start, past the expiration or was revoked. The response is a
+    `DenominationExpiredMessage`. Clients must evaluate
+    the error code provided to understand which of the
+    cases this is and handle it accordingly.
+
+  **Details:**
+
+  .. ts:def:: BatchDepositRequest
+
+    interface DepositRequest {
+
+      // The merchant's account details.
+      merchant_payto_uri: string;
+
+      // The salt is used to hide the ``payto_uri`` from customers
+      // when computing the ``h_wire`` of the merchant.
+      wire_salt: WireSalt;
+
+      // SHA-512 hash of the contract of the merchant with the customer.  Further
+      // details are never disclosed to the exchange.
+      h_contract_terms: HashCode;
+
+      // Timestamp when the contract was finalized.
+      timestamp: Timestamp;
+
+      // Indicative time by which the exchange undertakes to transfer the funds to
+      // the merchant, in case of successful payment. A wire transfer deadline of 'never'
+      // is not allowed.
+      wire_transfer_deadline: Timestamp;
+
+      // EdDSA `public key of the merchant <merchant-pub>`, so that the client can identify the
+      // merchant for refund requests.
+      merchant_pub: EddsaPublicKey;
+
+      // Date until which the merchant can issue a refund to the customer via the
+      // exchange, to be omitted if refunds are not allowed.
+      refund_deadline?: Timestamp;
+    }
+
+  .. ts:def:: DepositRequest
+
+    interface DepositRequest {
+      // EdDSA public key of the coin being deposited.
+      coin_pub: EddsaPublicKey;
+
+      // Hash of denomination RSA key with which the coin is signed.
+      denom_pub_hash: HashCode;
+
+      // Exchange's unblinded RSA signature of the coin.
+      ub_sig: DenominationSignature;
+
+      // Amount to be deposited, can be a fraction of the
+      // coin's total value.
+      contribution: Amount;
+
+      // Signature over `TALER_DepositRequestPS`, made by the customer with the
+      // `coin's private key <coin-priv>`.
+      coin_sig: EddsaSignature;
+    }
+ 
+  The deposit operation succeeds if the coin is valid for making a deposit and
+  has enough residual value that has not already been deposited or melted.
+
+  .. ts:def:: BatchDepositSuccess
+
+     interface BatchDepositSuccess {
+      // Optional base URL of the exchange for looking up wire transfers
+      // associated with this transaction.  If not given,
+      // the base URL is the same as the one used for this request.
+      // Can be used if the base URL for ``/transactions/`` differs from that
+      // for ``/coins/``, i.e. for load balancing.  Clients SHOULD
+      // respect the ``transaction_base_url`` if provided.  Any HTTP server
+      // belonging to an exchange MUST generate a 307 or 308 redirection
+      // to the correct base URL should a client uses the wrong base
+      // URL, or if the base URL has changed since the deposit.
+      transaction_base_url?: string;
+
+      // Timestamp when the deposit was received by the exchange.
+      exchange_timestamp: Timestamp;
+
+      // `Public EdDSA key of the exchange <sign-key-pub>` that was used to
+      // generate the signature.
+      // Should match one of the exchange's signing keys from ``/keys``.  It is given
+      // explicitly as the client might otherwise be confused by clock skew as to
+      // which signing key was used.
+      exchange_pub: EddsaPublicKey;
+
+      // Array of deposit confirmation signatures from the exchange
+      // Entries must be in the same order the coins were given
+      // in the batch deposit request.
+      exchange_sigs[]: DepositConfirmationSignature;
+    }
+
+  .. ts:def:: DepositConfirmationSignature
+ 
+    interface DepositConfirmationSignature {
+      // The EdDSA signature of `TALER_DepositConfirmationPS` using a current
+      // `signing key of the exchange <sign-key-priv>` affirming the successful
+      // deposit and that the exchange will transfer the funds after the refund
+      // deadline, or as soon as possible if the refund deadline is zero.
+      exchange_sig: EddsaSignature;
+    }
+
+    
 ----------
 Refreshing
 ----------