taler-docs

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

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

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