taler-docs

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

prepare-pay-for-paivana.rst (2139B)

      1 .. ts:op:: preparePayForPaivana
      2 
      3   Prepare a payment for an HTTP(S) resource protected by a Paivana
      4   paywall.
      5 
      6   The wallet requests the given ``url``, expects an HTTP 402 response
      7   that advertises a payment template in the ``Paivana`` header,
      8   instantiates that template into an order and creates (or reuses) a
      9   payment transaction for it.  The returned ``paivana`` redemption
     10   metadata must be kept by the client; once the payment has succeeded,
     11   it is passed to :ts:op:`getPaivanaCookie` to obtain the access cookie
     12   for the resource.
     13 
     14   **Request:**
     15 
     16     The ``args`` must be a `PreparePayForPaivanaRequest` object.
     17 
     18   **Response:**
     19 
     20     On success, the result is a `PreparePayForPaivanaResult` object.
     21 
     22   **Side effects:**
     23 
     24     Fetches the contract terms for the Paivana-protected resource over
     25     the network and creates a payment transaction in dialog state.
     26 
     27   **Expected errors:**
     28 
     29     The caller can handle the following errors inline:
     30     ``WALLET_CORE_API_BAD_REQUEST``,
     31     ``WALLET_RECEIVED_MALFORMED_RESPONSE``, ``WALLET_NETWORK_ERROR``,
     32     ``WALLET_HTTP_REQUEST_THROTTLED``,
     33     ``WALLET_HTTP_REQUEST_GENERIC_TIMEOUT``,
     34     ``WALLET_UNEXPECTED_REQUEST_ERROR``,
     35     ``WALLET_CONTRACT_TERMS_UNSUPPORTED``.
     36 
     37 .. ts:def:: PreparePayForPaivanaRequest
     38 
     39   interface PreparePayForPaivanaRequest {
     40     // URL of the Paivana-protected resource to pay for.
     41     url: string;
     42 
     43     // Enables progress correlation and cancellation through
     44     // cancelProgressToken.
     45     progressToken?: string;
     46   }
     47 
     48 .. ts:def:: PreparePayForPaivanaResult
     49 
     50   interface PreparePayForPaivanaResult {
     51     // Transaction identifier of the payment transaction.
     52     transactionId: TransactionIdStr;
     53 
     54     paivana: PaivanaRedemption;
     55   }
     56 
     57 .. ts:def:: PaivanaRedemption
     58 
     59   // Information needed to redeem a paid Paivana order for an
     60   // access cookie.
     61   interface PaivanaRedemption {
     62     // Canonical HTTP(S) URL of the protected resource.
     63     url: string;
     64 
     65     // Crockford-base32 encoded 16-byte client nonce.
     66     nonce: string;
     67 
     68     // End of the access period used to derive the Paivana
     69     // session ID.
     70     expiration: TalerProtocolTimestamp;
     71   }