taler-docs

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

get-private-incoming.rst (3258B)

      1 .. http:get:: [/instances/$INSTANCE]/private/incoming
      2 
      3   Obtain a list of expected incoming wire transfers the backend is
      4   anticipating.
      5   Since protocol **v20**.
      6 
      7   **Required permission:** ``transfers-read``
      8 
      9   **Request:**
     10 
     11   :query payto_uri: *Optional*. Full payto://-URI to filter for transfers to the given bank account (subject and amount MUST NOT be given in the payto:// URI).  Note that the URI must be URL-encoded.
     12 
     13   :query before: *Optional*. Filter for transfers executed before the given timestamp.
     14 
     15   :query after: *Optional*. Filter for transfers executed after the given timestamp.
     16 
     17   :query limit: *Optional*. At most return the given number of results. Negative for descending in execution time, positive for ascending in execution time. Default is ``-20``.
     18 
     19   :query offset: *Optional*. Starting ``expected_transfer_serial_id`` for an iteration.
     20 
     21   :query verified: *Optional*. Filter transfers by verification status (YES: reconcilation worked, NO: reconciliation failed, ALL: default)
     22 
     23   :query confirmed: *Optional*. Filter transfers that were confirmed (YES: credit confirmed, NO: credit still pending, ALL: default)
     24 
     25 
     26   **Response:**
     27 
     28   :http:statuscode:`200 OK`:
     29     The body of the response is a `ExpectedTransferListResponse`.
     30 
     31   **Details:**
     32 
     33   .. ts:def:: ExpectedTransferListResponse
     34 
     35     interface ExpectedTransferListResponse {
     36        // List of all the expected incoming transfers that fit the
     37        // filter that we know.
     38        incoming : ExpectedTransferEntry[];
     39     }
     40 
     41   .. ts:def:: ExpectedTransferEntry
     42 
     43     interface ExpectedTransferEntry {
     44       // How much should be wired to the merchant (minus fees).
     45       expected_credit_amount?: Amount;
     46 
     47       // Raw wire transfer identifier identifying the wire transfer (a base32-encoded value).
     48       wtid: WireTransferIdentifierRawP;
     49 
     50       // Full payto://-URI of the bank account that received the wire transfer.
     51       payto_uri: string;
     52 
     53       // Base URL of the exchange that made the wire transfer.
     54       exchange_url: string;
     55 
     56       // Serial number identifying the expected transfer in the backend.
     57       // Used for filtering via ``offset``.
     58       expected_transfer_serial_id: Integer;
     59 
     60       // Expected time of the execution of the wire transfer
     61       // by the exchange, according to the exchange.
     62       execution_time?: Timestamp;
     63 
     64       // True if we checked the exchange's answer and are happy with
     65       // the reconciation data.
     66       // False if we have an answer and are unhappy, missing if we
     67       // do not have an answer from the exchange.
     68       // Does not imply that the wire transfer was settled (for
     69       // that, see ``confirmed``).
     70       validated: boolean;
     71 
     72       // True if the merchant uses the POST /transfers API to confirm
     73       // that this wire transfer took place (and it is thus not
     74       // something merely claimed by the exchange).
     75       // (a matching entry exists in /private/transfers)
     76       confirmed: boolean;
     77 
     78       // Last HTTP status we received from the exchange, 0 for
     79       // none (incl. timeout)
     80       last_http_status: Integer;
     81 
     82       // Last Taler error code we got from the exchange.
     83       last_ec: ErrorCode;
     84 
     85       // Last error detail we got back from the exchange.
     86       last_error_detail?: string;
     87     }