get-private-transfers.rst (3825B)
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`` (see :ref:`Scopes <merchant-api-scopes>`) 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 // Full payto://-URI of the exchange's own bank account that was 59 // debited, useful to locate the transfer in a bank statement. 60 // Optional: only exchanges implementing exchange protocol **v39** 61 // report it, and even those only for transfers made after they 62 // started to record it. 63 // Since protocol **v35**. 64 exchange_payto_uri?: string; 65 66 // Base URL of the exchange that made the wire transfer. 67 exchange_url: WebURL; 68 69 // Serial number identifying the transfer in the merchant backend. 70 // Used for filtering via ``offset``. 71 transfer_serial_id: Integer; 72 73 // Serial number identifying the expected transfer in the 74 // merchant backend. Only given if ``expected`` is true. 75 // Used to obtain details about the settled orders. 76 // Since protocol **v27**. 77 expected_transfer_serial_id?: Integer; 78 79 // Time of the execution of the wire transfer. 80 // Missing if unknown in protocol **v25**. 81 execution_time?: Timestamp; 82 83 // True if we checked the exchange's answer and are happy with it. 84 // False if we have an answer and are unhappy, missing if we 85 // do not have an answer from the exchange. 86 // Removed in protocol **v20**. 87 verified?: boolean; 88 89 // True if the merchant uses the POST /transfers API to confirm 90 // that this wire transfer took place (and it is thus not 91 // something merely claimed by the exchange). 92 // Removed in protocol **v20**. 93 confirmed?: boolean; 94 95 // True if this wire transfer was expected. 96 // (a matching "/private/incoming" record exists). 97 // Since protocol **v20**. 98 expected?: boolean; 99 }