commit 68b0b21b33f78320f9209faeac9e1f57a7c536c1
parent e1dd76e8fb75f905ab7ffb263e94f8a43778aa07
Author: Antoine A <>
Date: Tue, 6 Aug 2024 16:07:39 +0200
wire-gateway: add transfer status endpoint
Diffstat:
1 file changed, 131 insertions(+), 1 deletion(-)
diff --git a/core/api-bank-wire.rst b/core/api-bank-wire.rst
@@ -29,7 +29,7 @@ LibEuFin (work in progress).
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being version **2**.
+ This specification corresponds to ``current`` protocol being version **3**.
**Response:**
@@ -141,6 +141,136 @@ Making Transactions
row_id: SafeUint64;
}
+.. http:get:: /transfers
+
+ Return a list of transfers initiated from the exchange.
+
+ The bank account of the exchange is determined via the base URL and/or the
+ user name in the ``Authorization`` header. The transfer history
+ might come from a "virtual" account, where multiple real bank accounts are
+ merged into one history.
+
+ Since protocol **v3**.
+
+ **Request:**
+
+ :query limit: *Optional.*
+ At most return the given number of results. Negative for descending by
+ ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``.
+ :query offset: *Optional.*
+ Starting ``row_id`` for :ref:`pagination <row-id-pagination>`.
+ :query status: *Optional*.
+ Filters by status.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ JSON object of type `TransferList`.
+ :http:statuscode:`204 No content`:
+ There are no transfers to report (under the given filter).
+ :http:statuscode:`400 Bad request`:
+ Request malformed.
+ :http:statuscode:`401 Unauthorized`:
+ Authentication failed, likely the credentials are wrong.
+ :http:statuscode:`404 Not found`:
+ The endpoint is wrong or the user name is unknown.
+
+ **Details:**
+
+ .. ts:def:: TransferList
+
+ interface TransferList {
+ // Array of initiated transfers.
+ transfers : TransferListStatus[];
+ }
+
+ .. ts:def:: TransferListStatus
+
+ interface TransferListStatus {
+ // Opaque ID of the wire transfer initiation performed by the bank.
+ // It is different from the /history endpoints row_id.
+ row_id: SafeUint64;
+
+ // Current status of the transfer
+ // pending: the transfer is in progress
+ // transient_failure: the transfer has failed but may succeed later
+ // permanent_failure: the transfer has failed permanently and will never appear in the outgoing history
+ // success: the transfer has succeeded and appears in the outgoing history
+ status: "pending" | "transient_failure" | "permanent_failure" | "success";
+
+ // Amount to transfer.
+ amount: Amount;
+
+ // The recipient's account identifier as a payto URI.
+ credit_account: string;
+
+ // Timestamp that indicates when the wire transfer was executed.
+ // In cases where the wire transfer gateway is unable to know when
+ // the wire transfer will be executed, the time at which the request
+ // has been received and stored will be returned.
+ // The purpose of this field is for debugging (humans trying to find
+ // the transaction) as well as for taxation (determining which
+ // time period a transaction belongs to).
+ timestamp: Timestamp;
+ }
+
+
+.. http:get:: /transfers/$ROW_ID
+
+ Return the status of a transfer initiated from the exchange, identified by the ``ROW_ID``.
+
+ Since protocol **v3**.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The transfer is known, and details are given in the `TransferStatus` response body.
+ :http:statuscode:`400 Bad request`:
+ Request malformed.
+ :http:statuscode:`401 Unauthorized`:
+ Authentication failed, likely the credentials are wrong.
+ :http:statuscode:`404 Not found`:
+ The transfer was not found.
+
+ **Details:**
+
+ .. ts:def:: TransferStatus
+
+ interface TransferStatus {
+ // Current status of the transfer
+ // pending: the transfer is in progress
+ // transient_failure: the transfer has failed but may succeed later
+ // permanent_failure: the transfer has failed permanently and will never appear in the outgoing history
+ // success: the transfer has succeeded and appears in the outgoing history
+ status: "pending" | "transient_failure" | "permanent_failure" | "success";
+
+ // Optional unstructured messages about the transfer's status. Can be used to document the reasons for failure or the state of progress.
+ status_msg: string?;
+
+ // Amount to transfer.
+ amount: Amount;
+
+ // Base URL of the exchange. Shall be included by the bank gateway
+ // in the appropriate section of the wire transfer details.
+ exchange_base_url: string;
+
+ // Wire transfer identifier chosen by the exchange,
+ // used by the merchant to identify the Taler order(s)
+ // associated with this wire transfer.
+ wtid: ShortHashCode;
+
+ // The recipient's account identifier as a payto URI.
+ credit_account: string;
+
+ // Timestamp that indicates when the wire transfer was executed.
+ // In cases where the wire transfer gateway is unable to know when
+ // the wire transfer will be executed, the time at which the request
+ // has been received and stored will be returned.
+ // The purpose of this field is for debugging (humans trying to find
+ // the transaction) as well as for taxation (determining which
+ // time period a transaction belongs to).
+ timestamp: Timestamp;
+ }
--------------------------------
Querying the transaction history
