taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

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

      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:`403 Forbidden`:
     16     A coin or denomination signature is invalid.
     17     This response comes with a standard `ErrorDetail` response.
     18   :http:statuscode:`404 Not found`:
     19     The purse is unknown.
     20     This response comes with a standard `ErrorDetail` response.
     21   :http:statuscode:`409 Conflict`:
     22     The deposit operation has either failed because a coin has insufficient
     23     residual value, or because the same public key of the coin has been
     24     previously used with a different denomination.  Which case it is
     25     can be decided by looking at the error code
     26     (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or
     27     ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` or
     28     ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA``).
     29     This response comes with a standard `PurseConflict` response
     30     (alas some cases are impossible).
     31   :http:statuscode:`410 Gone`:
     32     The purse has expired.
     33 
     34 
     35   **Details:**
     36 
     37    .. ts:def:: PurseDeposits
     38 
     39     interface PurseDeposits {
     40 
     41       // Array of coins to deposit into the purse.
     42       deposits: PurseDeposit[];
     43     }
     44 
     45   .. ts:def:: PurseDeposit
     46 
     47     interface PurseDeposit {
     48 
     49       // Amount to be deposited, can be a fraction of the
     50       // coin's total value.
     51       amount: Amount;
     52 
     53       // Hash of denomination RSA key with which the coin is signed.
     54       denom_pub_hash: HashCode;
     55 
     56       // Exchange's unblinded RSA signature of the coin.
     57       ub_sig: DenominationSignature;
     58 
     59       // Age commitment for the coin, if the denomination is age-restricted.
     60       age_commitment?: AgeCommitment;
     61 
     62       // Attestation for the minimum age, if the denomination is age-restricted.
     63       attest?: Attestation;
     64 
     65       // Signature over `TALER_PurseDepositSignaturePS`
     66       // of purpose ``TALER_SIGNATURE_WALLET_PURSE_DEPOSIT``
     67       // made by the customer with the
     68       // `coin's private key <coin-priv>`.
     69       coin_sig: EddsaSignature;
     70 
     71       // Public key of the coin being deposited into the purse.
     72       coin_pub: EddsaPublicKey;
     73 
     74     }
     75 
     76   .. ts:def:: PurseDepositSuccessResponse
     77 
     78      interface PurseDepositSuccessResponse {
     79 
     80       // Total amount paid into the purse.
     81       total_deposited: Amount;
     82 
     83       // Total amount expected in the purse.
     84       purse_value_after_fees: Amount;
     85 
     86       // Time at which the deposit came into effect.
     87       exchange_timestamp: Timestamp;
     88 
     89       // Indicative time by which the purse should expire
     90       // if it has not been merged into an account. At this
     91       // point, all of the deposits made will be auto-refunded.
     92       purse_expiration: Timestamp;
     93 
     94       // SHA-512 hash of the contact of the purse.
     95       h_contract_terms: HashCode;
     96 
     97       // EdDSA signature of the exchange affirming the payment,
     98       // of purpose ``TALER_SIGNATURE_PURSE_DEPOSIT_CONFIRMED``
     99       // over a `TALER_PurseDepositConfirmedSignaturePS`.
    100       // Signs over the above and the purse public key and
    101       // the hash of the contract terms.
    102       exchange_sig: EddsaSignature;
    103 
    104       // public key used to create the signature.
    105       exchange_pub: EddsaPublicKey;
    106 
    107     }
    108 
    109   .. ts:def:: AgeCommitment
    110 
    111      // AgeCommitment is an array of public keys, one for each age group of the
    112      // age-restricted denomination.
    113      type AgeCommitment = Edx25519PublicKey[];
    114 
    115   .. ts:def:: Attestation
    116 
    117      // An attestation for a minimum age is an Edx25519 signature of the age
    118      // with purpose ``TALER_SIGNATURE_WALLET_AGE_ATTESTATION``.
    119      type Attestation = string;