taler-docs

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

initiate-peer-push-debit.rst (2021B)

      1 .. ts:op:: initiatePeerPushDebit
      2 
      3   Initiate an outgoing peer push payment.
      4 
      5   **Request:**
      6 
      7   The request body must be an `InitiatePeerPushDebitRequest` object.
      8 
      9   **Response:**
     10 
     11   On success, the result is an `InitiatePeerPushDebitResponse`
     12   object.
     13 
     14   **Side effects:**
     15 
     16   Creates an outgoing peer push payment transaction, locking the
     17   coins.
     18 
     19   **Expected errors:**
     20 
     21   The caller can handle the following errors inline:
     22   ``WALLET_PEER_PUSH_PAYMENT_INSUFFICIENT_BALANCE``,
     23   ``WALLET_PEER_PUSH_PAYMENT_QUOTE_CHANGED``,
     24   ``WALLET_CORE_API_BAD_REQUEST``.
     25 
     26   **Details:**
     27 
     28   ``exchangeBaseUrl`` and ``restrictScope`` are mutually exclusive.
     29   The ``purse_expiration`` in ``partialContractTerms`` must be finite
     30   and in the future.  When a ``peerPushDebitQuote`` obtained from
     31   :ts:op:`checkPeerPushDebitV2` is passed, an explicit expiration is
     32   required, and wallet-core rejects the request when it does not match
     33   the quote or when the coin selection, fees or the selected exchange
     34   changed since the quote was made.
     35 
     36   The ``taler://pay-push/`` URI to hand to the receiver is not part of
     37   the response; it is available from the transaction (see
     38   :ts:op:`getTransactionById`) once the transaction is pending.
     39 
     40 .. ts:def:: InitiatePeerPushDebitRequest
     41 
     42   interface InitiatePeerPushDebitRequest {
     43     exchangeBaseUrl?: string;
     44 
     45     // Restrict the scope of funds that can be spent via the given
     46     // scope info.
     47     restrictScope?: ScopeInfo;
     48 
     49     // Quote returned by checkPeerPushDebitV2.
     50     peerPushDebitQuote?: string;
     51 
     52     partialContractTerms: PartialPeerContractTerms;
     53   }
     54 
     55 .. ts:def:: PartialPeerContractTerms
     56 
     57   interface PartialPeerContractTerms {
     58     amount: AmountString;
     59     summary: string;
     60     icon_id?: string;
     61     purse_expiration?: TalerProtocolTimestamp;
     62   }
     63 
     64 .. ts:def:: InitiatePeerPushDebitResponse
     65 
     66   interface InitiatePeerPushDebitResponse {
     67     exchangeBaseUrl: string;
     68     pursePub: string;
     69     mergePriv: string;
     70     contractPriv: string;
     71     transactionId: TransactionIdStr;
     72   }