taler-docs

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

post-purses-PURSE_PUB-create.rst (8449B)

      1 .. http:post:: /purses/$PURSE_PUB/create
      2 
      3   Create a purse by depositing money into it. First step of a PUSH payment.
      4 
      5   **Request:**
      6 
      7   The request body must be a `PurseCreateRequest` 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 `PurseCreateSuccessResponse` object.
     15   :http:statuscode:`400 Bad Request`:
     16     The request is malformed or a parameter is invalid.
     17     This response comes with a standard `ErrorDetail` response.
     18     Possible error codes include ``TALER_EC_GENERIC_PARAMETER_MALFORMED``,
     19     ``TALER_EC_EXCHANGE_PURSE_CREATE_EXPIRATION_BEFORE_NOW``,
     20     ``TALER_EC_EXCHANGE_PURSE_CREATE_EXPIRATION_IS_NEVER``, or
     21     ``TALER_EC_EXCHANGE_CREATE_PURSE_NEGATIVE_VALUE_AFTER_FEE``.
     22   :http:statuscode:`403 Forbidden`:
     23     A coin, denomination or contract signature is invalid.
     24     This response comes with a standard `ErrorDetail` response.
     25     Possible error codes include
     26     ``TALER_EC_EXCHANGE_PURSE_CREATE_SIGNATURE_INVALID`` or
     27     ``TALER_EC_EXCHANGE_PURSE_ECONTRACT_SIGNATURE_INVALID``.
     28   :http:statuscode:`404 Not Found`:
     29     The denomination of one of the coins is unknown to the exchange.
     30   :http:statuscode:`409 Conflict`:
     31     The deposit operation has either failed because a coin has insufficient
     32     residual value, or because the same public key of the coin has been
     33     previously used with a different denomination, or because a purse with
     34     the same public key but different meta data was created previously.
     35     Which case it is
     36     can be decided by looking at the error code
     37     (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or
     38     ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` or
     39     ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_AGE_HASH`` or
     40     ``TALER_EC_EXCHANGE_PURSE_CREATE_CONFLICTING_META_DATA`` or
     41     ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA`` or
     42     ``TALER_EC_EXCHANGE_PURSE_ECONTRACT_CONFLICTING_META_DATA``).
     43     The specific fields of the response depend on the error code
     44     and include the signatures (and what was signed over) proving the
     45     conflict.  The response is a `PurseConflict`.
     46   :http:statuscode:`410 Gone`:
     47     The requested denomination key is not yet or no longer valid.
     48     It either before the validity start, past the expiration or was revoked.
     49     The response is a `DenominationGoneMessage`. Clients must evaluate
     50     the error code provided to understand which of the
     51     cases this is and handle it accordingly.
     52   :http:statuscode:`413 Request entity too large`:
     53     The uploaded body is to long, it exceeds the size limit.
     54     Returned with an error code of
     55     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     56   :http:statuscode:`425 Too Early`:
     57     This response type is used if the given purse expiration time
     58     is too far in the future (at least from the perspective
     59     of the exchange). Thus, retrying at a later time may
     60     succeed. The client should look at the ``Date:`` header
     61     of the response to see if a minor time difference is to
     62     blame and possibly adjust the request accordingly.
     63     (Note: this status code is not yet used.)
     64   :http:statuscode:`500 Internal Server Error`:
     65     The exchange encountered an internal error.
     66     This response comes with a standard `ErrorDetail` response.
     67     Possible error codes include
     68     ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING``,
     69     ``TALER_EC_EXCHANGE_GENERIC_GLOBAL_FEES_MISSING``,
     70     ``TALER_EC_GENERIC_DB_STORE_FAILED``,
     71     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     72     ``TALER_EC_GENERIC_DB_START_FAILED``, or
     73     ``TALER_EC_GENERIC_FAILED_COMPUTE_AMOUNT``.
     74 
     75 
     76   **Details:**
     77 
     78   .. ts:def:: PurseCreateRequest
     79 
     80     interface PurseCreateRequest {
     81 
     82       // Total value of the purse, excluding fees.
     83       amount: Amount;
     84 
     85       // Minimum age required for all coins deposited into the purse.
     86       min_age: Integer;
     87 
     88       // Optional encrypted contract, in case the buyer is
     89       // proposing the contract and thus establishing the
     90       // purse with the payment.
     91       econtract?: EncryptedContract;
     92 
     93       // EdDSA public key used to approve merges of this purse.
     94       merge_pub: EddsaPublicKey;
     95 
     96       // EdDSA signature of the purse over a
     97       // `TALER_PurseRequestSignaturePS`
     98       // of purpose ``TALER_SIGNATURE_WALLET_PURSE_CREATE``
     99       // confirming the key
    100       // invariants associated with the purse.
    101       // (amount, h_contract_terms, expiration).
    102       purse_sig: EddsaSignature;
    103 
    104       // SHA-512 hash of the contact of the purse.
    105       h_contract_terms: HashCode;
    106 
    107       // Array of coins being deposited into the purse.
    108       // Maximum length is 128.
    109       deposits: PurseDeposit[];
    110 
    111       // Indicative time by which the purse should expire
    112       // if it has not been merged into an account. At this
    113       // point, all of the deposits made will be auto-refunded.
    114       purse_expiration: Timestamp;
    115 
    116     }
    117 
    118   .. ts:def:: EncryptedContract
    119 
    120     interface EncryptedContract {
    121 
    122       // Encrypted contract.
    123       econtract: string;
    124 
    125       // Signature over the (encrypted) contract.
    126       econtract_sig: EddsaSignature;
    127 
    128       // Ephemeral public key for the DH operation to decrypt the encrypted contract.
    129       contract_pub: EddsaPublicKey;
    130 
    131     }
    132 
    133   .. ts:def:: PurseCreateSuccessResponse
    134 
    135      interface PurseCreateSuccessResponse {
    136 
    137       // Total amount deposited into the purse so far (without fees).
    138       total_deposited: Amount;
    139 
    140       // Time at the exchange.
    141       exchange_timestamp: Timestamp;
    142 
    143       // EdDSA signature of the exchange affirming the payment,
    144       // of purpose ``TALER_SIGNATURE_PURSE_DEPOSIT_CONFIRMED``
    145       // over a `TALER_PurseDepositConfirmedSignaturePS`.
    146       // Signs over the above and the purse public key and
    147       // the hash of the contract terms.
    148       exchange_sig: EddsaSignature;
    149 
    150       // public key used to create the signature.
    151       exchange_pub: EddsaPublicKey;
    152 
    153     }
    154 
    155   .. ts:def:: PurseConflict
    156 
    157     // Union discriminated by the "code" field.
    158     type PurseConflict =
    159     | DepositDoubleSpendError
    160     | CoinDenominationConflictError
    161     | CoinAgeCommitmentConflictError
    162     | PurseCreateConflict
    163     | PurseDepositConflict
    164     | PurseContractConflict;
    165 
    166   .. ts:def:: PurseCreateConflict
    167 
    168     interface PurseCreateConflict {
    169       // Must be equal to TALER_EC_EXCHANGE_PURSE_CREATE_CONFLICTING_META_DATA
    170       code: Integer;
    171 
    172       // Total amount to be merged into the reserve.
    173       // (excludes fees).
    174       amount: Amount;
    175 
    176       // Minimum age required for all coins deposited into the purse.
    177       min_age: Integer;
    178 
    179       // Indicative time by which the purse should expire
    180       // if it has not been merged into an account. At this
    181       // point, all of the deposits made should be
    182       // auto-refunded.
    183       purse_expiration: Timestamp;
    184 
    185       // EdDSA signature of the purse over
    186       // `TALER_PurseMergeSignaturePS` of
    187       // purpose ``TALER_SIGNATURE_WALLET_PURSE_MERGE``
    188       // confirming that the
    189       // above details hold for this purse.
    190       purse_sig: EddsaSignature;
    191 
    192       // SHA-512 hash of the contact of the purse.
    193       h_contract_terms: HashCode;
    194 
    195       // EdDSA public key used to approve merges of this purse.
    196       merge_pub: EddsaPublicKey;
    197     }
    198 
    199   .. ts:def:: PurseDepositConflict
    200 
    201     interface PurseDepositConflict {
    202       // Must be equal to TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA
    203       code: Integer;
    204 
    205       // Public key of the coin being deposited into the purse.
    206       coin_pub: EddsaPublicKey;
    207 
    208       // Signature over `TALER_PurseDepositSignaturePS`
    209       // of purpose ``TALER_SIGNATURE_WALLET_PURSE_DEPOSIT``
    210       // made by the customer with the
    211       // `coin's private key <coin-priv>`.
    212       coin_sig: EddsaSignature;
    213 
    214       // Target exchange URL for the purse. Not present for the
    215       // same exchange.
    216       partner_url?: WebURL;
    217 
    218       // Amount to be contributed to the purse by this coin.
    219       amount: Amount;
    220 
    221     }
    222 
    223   .. ts:def:: PurseContractConflict
    224 
    225     interface PurseContractConflict {
    226       // Must be equal to TALER_EC_EXCHANGE_PURSE_ECONTRACT_CONFLICTING_META_DATA
    227       code: Integer;
    228 
    229       // Hash of the encrypted contract.
    230       h_econtract: HashCode;
    231 
    232       // Signature over the contract.
    233       econtract_sig: EddsaSignature;
    234 
    235       // Ephemeral public key for the DH operation to decrypt the contract.
    236       contract_pub: EddsaPublicKey;
    237 
    238     }