taler-docs

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

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


      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     // Minimum acceptable access expiry bound into the Paivana session ID.
     69     expiration: TalerProtocolTimestamp;
     70   }