taler-docs

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

get-private-transfers.rst (3400B)

      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   :http:statuscode:`401 Unauthorized`:
     30     The request is unauthorized.
     31   :http:statuscode:`404 Not found`:
     32     The instance is unknown.
     33   :http:statuscode:`500 Internal Server Error`:
     34     The server experienced an internal failure.
     35     Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
     36 
     37   **Details:**
     38 
     39   .. ts:def:: TransferList
     40 
     41     interface TransferList {
     42        // List of all the transfers that fit the filter that we know.
     43        transfers : TransferDetails[];
     44     }
     45 
     46   .. ts:def:: TransferDetails
     47 
     48     interface TransferDetails {
     49       // How much was wired to the merchant (minus fees).
     50       credit_amount: Amount;
     51 
     52       // Raw wire transfer identifier identifying the wire transfer (a base32-encoded value).
     53       wtid: WireTransferIdentifierRawP;
     54 
     55       // Full payto://-URI of the bank account that received the wire transfer.
     56       payto_uri: string;
     57 
     58       // Base URL of the exchange that made the wire transfer.
     59       exchange_url: string;
     60 
     61       // Serial number identifying the transfer in the merchant backend.
     62       // Used for filtering via ``offset``.
     63       transfer_serial_id: Integer;
     64 
     65       // Serial number identifying the expected transfer in the
     66       // merchant backend. Only given if ``expected`` is true.
     67       // Used to obtain details about the settled orders.
     68       // Since protocol **v27**.
     69       expected_transfer_serial_id?: Integer;
     70 
     71       // Time of the execution of the wire transfer.
     72       // Missing if unknown in protocol **v25**.
     73       execution_time?: Timestamp;
     74 
     75       // True if we checked the exchange's answer and are happy with it.
     76       // False if we have an answer and are unhappy, missing if we
     77       // do not have an answer from the exchange.
     78       // Removed in protocol **v20**.
     79       verified?: boolean;
     80 
     81       // True if the merchant uses the POST /transfers API to confirm
     82       // that this wire transfer took place (and it is thus not
     83       // something merely claimed by the exchange).
     84       // Removed in protocol **v20**.
     85       confirmed?: boolean;
     86 
     87       // True if this wire transfer was expected.
     88       // (a matching "/private/incoming" record exists).
     89       // Since protocol **v20**.
     90       expected?: boolean;
     91     }