taler-docs

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

get-transfers.rst (2871B)

      1 .. http:get:: /transfers
      2 
      3   Return a list of transfers initiated from the exchange.
      4 
      5   The bank account of the exchange is determined via the base URL and/or the
      6   user name in the ``Authorization`` header. The transfer history
      7   might come from a "virtual" account, where multiple real bank accounts are
      8   merged into one history.
      9 
     10   Since protocol **v3**.
     11 
     12   **Request:**
     13 
     14   :query limit: *Optional.*
     15     At most return the given number of results. Negative for descending by
     16     ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``.
     17   :query offset: *Optional.*
     18     Starting ``row_id`` for :ref:`pagination <row-id-pagination>`.
     19   :query status: *Optional*.
     20     Filters by status.
     21 
     22   **Response:**
     23 
     24   :http:statuscode:`200 OK`:
     25     JSON object of type `TransferList`.
     26   :http:statuscode:`204 No content`:
     27     There are no transfers to report (under the given filter).
     28   :http:statuscode:`400 Bad request`:
     29     Request malformed.
     30   :http:statuscode:`401 Unauthorized`:
     31     Authentication failed, likely the credentials are wrong.
     32   :http:statuscode:`404 Not found`:
     33     The endpoint is wrong or the user name is unknown.
     34 
     35   **Details:**
     36 
     37   .. ts:def:: TransferList
     38 
     39     interface TransferList {
     40       // Array of initiated transfers.
     41       transfers: TransferListStatus[];
     42 
     43       // Full payto:// URI to identify the sender of funds.
     44       // This must be one of the exchange's bank accounts.
     45       // Credit account is shared by all incoming transactions
     46       // as per the nature of the request.
     47       debit_account: string;
     48     }
     49 
     50   .. ts:def:: TransferListStatus
     51 
     52     interface TransferListStatus {
     53       // Opaque ID of the wire transfer initiation performed by the bank.
     54       // It is different from the /history endpoints row_id.
     55       row_id: SafeUint64;
     56 
     57       // Current status of the transfer
     58       // pending: the transfer is in progress
     59       // transient_failure: the transfer has failed but may succeed later
     60       // permanent_failure: the transfer has failed permanently and will never appear in the outgoing history
     61       // success: the transfer has succeeded  and appears in the outgoing history
     62       status: "pending" | "transient_failure" | "permanent_failure" | "success";
     63 
     64       // Amount to transfer.
     65       amount: Amount;
     66 
     67       // The recipient's account identifier as a full payto:// URI.
     68       credit_account: string;
     69 
     70       // Timestamp that indicates when the wire transfer was executed.
     71       // In cases where the wire transfer gateway is unable to know when
     72       // the wire transfer will be executed, the time at which the request
     73       // has been received and stored will be returned.
     74       // The purpose of this field is for debugging (humans trying to find
     75       // the transaction) as well as for taxation (determining which
     76       // time period a transaction belongs to).
     77       timestamp: Timestamp;
     78     }