taler-docs

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

get-private-transfers.rst (3111B)

      1 .. http:get:: [/instances/$INSTANCE]/private/transfers
      2 
      3   Obtain a list of all wire transfers the backend was told
      4   had been made into the merchant bank account.
      5   Since protocol **v20** this endpoint is only about
      6   actually confirmed wire transfers.
      7 
      8   **Required permission:** ``transfers-read``
      9 
     10   **Request:**
     11 
     12   :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.
     13 
     14   :query before: *Optional*. Filter for transfers executed before the given timestamp.
     15 
     16   :query after: *Optional*. Filter for transfers executed after the given timestamp.
     17 
     18   :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``.
     19 
     20   :query offset: *Optional*. Starting ``transfer_serial_id`` for an iteration.
     21 
     22   :query expected: *Optional*. Filter transfers that we expected to receive (YES: only expected, NO: only unexpected, ALL: default). Since protocol **v20**.
     23 
     24 
     25   **Response:**
     26 
     27   :http:statuscode:`200 OK`:
     28     The body of the response is a `TransferList`.
     29 
     30   **Details:**
     31 
     32   .. ts:def:: TransferList
     33 
     34     interface TransferList {
     35        // List of all the transfers that fit the filter that we know.
     36        transfers : TransferDetails[];
     37     }
     38 
     39   .. ts:def:: TransferDetails
     40 
     41     interface TransferDetails {
     42       // How much was wired to the merchant (minus fees).
     43       credit_amount: Amount;
     44 
     45       // Raw wire transfer identifier identifying the wire transfer (a base32-encoded value).
     46       wtid: WireTransferIdentifierRawP;
     47 
     48       // Full payto://-URI of the bank account that received the wire transfer.
     49       payto_uri: string;
     50 
     51       // Base URL of the exchange that made the wire transfer.
     52       exchange_url: string;
     53 
     54       // Serial number identifying the transfer in the merchant backend.
     55       // Used for filtering via ``offset``.
     56       transfer_serial_id: Integer;
     57 
     58       // Serial number identifying the expected transfer in the
     59       // merchant backend. Only given if ``expected`` is true.
     60       // Used to obtain details about the settled orders.
     61       // Since protocol **v27**.
     62       expected_transfer_serial_id?: Integer;
     63 
     64       // Time of the execution of the wire transfer.
     65       // Missing if unknown in protocol **v25**.
     66       execution_time?: Timestamp;
     67 
     68       // True if we checked the exchange's answer and are happy with it.
     69       // False if we have an answer and are unhappy, missing if we
     70       // do not have an answer from the exchange.
     71       // Removed in protocol **v20**.
     72       verified?: boolean;
     73 
     74       // True if the merchant uses the POST /transfers API to confirm
     75       // that this wire transfer took place (and it is thus not
     76       // something merely claimed by the exchange).
     77       // Removed in protocol **v20**.
     78       confirmed?: boolean;
     79 
     80       // True if this wire transfer was expected.
     81       // (a matching "/private/incoming" record exists).
     82       // Since protocol **v20**.
     83       expected?: boolean;
     84     }