taler-docs

post-purses-PURSE_PUB-deposit.rst (5494B)

---

 .. http:post:: /purses/$PURSE_PUB/deposit
 
   Deposit money into a purse. Used by the buyer for a PULL payment.
 
   **Request:**
 
   The request body must be a `PurseDeposits` object.
 
   A purse that is not decided refunds the coins deposited into it when it
   expires, and the exchange must still be able to account for that refund.
   A coin whose denomination would stop being legally valid before the
   purse expires is therefore refused.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The operation succeeded, the exchange confirms that all
     coins were deposited into the purse.
     The response will include a `PurseDepositSuccessResponse` object.
   :http:statuscode:`400 Bad Request`:
     The request body is malformed or a parameter is invalid.
     This response comes with a standard `ErrorDetail` response with
     a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` or of
     ``TALER_EC_EXCHANGE_PURSE_DENOMINATION_LEGAL_EXPIRES_TOO_SOON``,
     whose ``detail`` gives the ``stamp_expire_legal`` of the denomination
     that is too short-lived for this purse.
   :http:statuscode:`403 Forbidden`:
     A coin or denomination signature is invalid.
     This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`404 Not found`:
     The purse is unknown.
     This response comes with a standard `ErrorDetail` response with
     a code of ``TALER_EC_EXCHANGE_GENERIC_PURSE_UNKNOWN``.
   :http:statuscode:`409 Conflict`:
     The deposit operation has either failed because a coin has insufficient
     residual value, or because the same public key of the coin has been
     previously used with a different denomination or age commitment.
     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`` or
     ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_AGE_HASH`` or
     ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA``).
     This response comes with a standard `PurseConflict` response
     (alas some cases are impossible).
   :http:statuscode:`410 Gone`:
     The purse has expired, was deleted, or the deposit was already decided.
     Possible error codes include
     ``TALER_EC_EXCHANGE_GENERIC_PURSE_EXPIRED``,
     ``TALER_EC_EXCHANGE_GENERIC_PURSE_DELETED``, or
     ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_DECIDED_ALREADY``.
   :http:statuscode:`413 Request entity too large`:
     The uploaded body is to long, it exceeds the size limit.
     Returned with an error code of
     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
   :http:statuscode:`500 Internal Server Error`:
     The server experienced an internal error.
     This response comes with a standard `ErrorDetail` response.
     Possible error codes include
     ``TALER_EC_GENERIC_DB_STORE_FAILED``,
     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     ``TALER_EC_GENERIC_DB_START_FAILED``, or
     ``TALER_EC_GENERIC_FAILED_COMPUTE_AMOUNT``.
 
   **Details:**
 
   .. ts:def:: PurseDeposits
 
     interface PurseDeposits {
 
       // Array of coins to deposit into the purse.
       deposits: PurseDeposit[];
     }
 
   .. ts:def:: PurseDeposit
 
     interface PurseDeposit {
 
       // Amount to be deposited, can be a fraction of the
       // coin's total value.
       amount: Amount;
 
       // 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;
 
       // Age commitment for the coin, if the denomination is age-restricted.
       age_commitment?: AgeCommitment;
 
       // Attestation for the minimum age, if the denomination is age-restricted.
       attest?: Attestation;
 
       // Signature over `TALER_PurseDepositSignaturePS`
       // of purpose ``TALER_SIGNATURE_WALLET_PURSE_DEPOSIT``
       // made by the customer with the
       // `coin's private key <coin-priv>`.
       coin_sig: EddsaSignature;
 
       // Public key of the coin being deposited into the purse.
       coin_pub: EddsaPublicKey;
 
     }
 
   .. ts:def:: PurseDepositSuccessResponse
 
      interface PurseDepositSuccessResponse {
 
       // Total amount paid into the purse.
       total_deposited: Amount;
 
       // Total amount expected in the purse.
       purse_value_after_fees: Amount;
 
       // Time at which the deposit came into effect.
       exchange_timestamp: Timestamp;
 
       // Indicative time by which the purse should expire
       // if it has not been merged into an account. At this
       // point, all of the deposits made will be auto-refunded.
       purse_expiration: Timestamp;
 
       // SHA-512 hash of the contact of the purse.
       h_contract_terms: HashCode;
 
       // EdDSA signature of the exchange affirming the payment,
       // of purpose ``TALER_SIGNATURE_PURSE_DEPOSIT_CONFIRMED``
       // over a `TALER_PurseDepositConfirmedSignaturePS`.
       // Signs over the above and the purse public key and
       // the hash of the contract terms.
       exchange_sig: EddsaSignature;
 
       // public key used to create the signature.
       exchange_pub: EddsaPublicKey;
 
     }
 
   .. ts:def:: AgeCommitment
 
      // AgeCommitment is an array of public keys, one for each age group of the
      // age-restricted denomination.
      type AgeCommitment = Edx25519PublicKey[];
 
   .. ts:def:: Attestation
 
      // An attestation for a minimum age is an Edx25519 signature of the age
      // with purpose ``TALER_SIGNATURE_WALLET_AGE_ATTESTATION``.
      type Attestation = string;