taler-docs

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

prepare-peer-push-credit.rst (2170B)

      1 .. ts:op:: preparePeerPushCredit
      2 
      3   Check an incoming peer push payment.  The payment is identified
      4   either by a ``taler://pay-push/`` URI received from the sender or by
      5   the ``transactionId`` of an existing peer-push-credit transaction.
      6 
      7   **Request:**
      8 
      9   The request body must be a `PreparePeerPushCreditRequest` object.
     10   Either ``talerUri`` or ``transactionId`` must be specified.
     11 
     12   **Response:**
     13 
     14   On success, the result is a `PreparePeerPushCreditResponse` object,
     15   carrying the contract terms and the amounts the wallet would
     16   receive, so that the user can review the payment before accepting it
     17   with :ts:op:`confirmPeerPushCredit`.
     18 
     19   **Side effects:**
     20 
     21   Fetches the contract and purse status from the exchange over the
     22   network and creates an incoming peer push payment transaction in
     23   dialog state.
     24 
     25   **Expected errors:**
     26 
     27   The caller can handle the following errors inline:
     28   ``WALLET_PEER_CONTRACT_NOT_FOUND``,
     29   ``WALLET_PEER_PUSH_CREDIT_PURSE_GONE``, ``WALLET_TALER_URI_MALFORMED``,
     30   ``WALLET_TRANSACTION_NOT_FOUND``.
     31 
     32   **Details:**
     33 
     34   Calling the operation again with the same ``talerUri`` or with the
     35   resulting ``transactionId`` returns the state of the existing
     36   transaction instead of fetching the contract again.
     37 
     38 .. ts:def:: PreparePeerPushCreditRequest
     39 
     40   // Either talerUri or transactionId must be specified.
     41   interface PreparePeerPushCreditRequest {
     42     talerUri?: string;
     43     transactionId?: string;
     44 
     45     progressToken?: string;
     46   }
     47 
     48 .. ts:def:: PreparePeerPushCreditResponse
     49 
     50   interface PreparePeerPushCreditResponse {
     51     contractTerms: PeerContractTerms;
     52     amountRaw: AmountString;
     53     amountEffective: AmountString;
     54 
     55     transactionId: TransactionIdStr;
     56 
     57     // State of the existing or newly created transaction.
     58     txState: TransactionState;
     59 
     60     exchangeBaseUrl: string;
     61 
     62     scopeInfo: ScopeInfo;
     63 
     64     // Deprecated.
     65     amount: AmountString;
     66   }
     67 
     68 .. ts:def:: PeerContractTerms
     69 
     70   // Contract terms between two wallets (as opposed to a merchant and
     71   // wallet).
     72   interface PeerContractTerms {
     73     amount: AmountString;
     74     summary: string;
     75     icon_id?: string;
     76     purse_expiration: TalerProtocolTimestamp;
     77   }