commit 24636bd88dc274b57c2925a1ffbf98ce48024ae7
parent fdb8d9061078ec97ea18b1a3d333531abec4a4d0
Author: Antoine A <>
Date: Mon, 30 Sep 2024 17:51:05 +0200
wg: add outgoing failures history endpoint and late_failure transfer
status
Diffstat:
1 file changed, 73 insertions(+), 5 deletions(-)
diff --git a/core/api-bank-wire.rst b/core/api-bank-wire.rst
@@ -245,10 +245,11 @@ Making Transactions
interface TransferStatus {
// Current status of the transfer
// pending: the transfer is in progress
+ // success: the transfer has succeeded and appears in the outgoing history
// 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";
+ // late_failure: the transfer has succeeded then failed, it appears both in the outgoing success & failures histories
+ status: "pending" | "success" | "transient_failure" | "permanent_failure" | "late_failure";
// 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;
@@ -315,7 +316,7 @@ accounts are merged into a single history.
:http:statuscode:`200 OK`:
JSON object of type `IncomingHistory`.
:http:statuscode:`204 No content`:
- There are not transactions to report (under the given filter).
+ There are no transactions to report (under the given filter).
:http:statuscode:`400 Bad request`:
Request malformed. The bank replies with an `ErrorDetail` object.
:http:statuscode:`401 Unauthorized`:
@@ -416,7 +417,7 @@ accounts are merged into a single history.
.. http:get:: /history/outgoing
- Return a list of transactions made by the exchange, typically to a merchant.
+ Return a list of successfull transactions made by the exchange, typically to a merchant.
**Request:**
@@ -438,7 +439,7 @@ accounts are merged into a single history.
:http:statuscode:`200 OK`:
JSON object of type `OutgoingHistory`.
:http:statuscode:`204 No content`:
- There are not transactions to report (under the given filter).
+ There are no transactions to report (under the given filter).
:http:statuscode:`400 Bad request`:
Request malformed. The bank replies with an `ErrorDetail` object.
:http:statuscode:`401 Unauthorized`:
@@ -483,6 +484,73 @@ accounts are merged into a single history.
exchange_base_url: string;
}
+.. http:get:: /history/outgoing-failures
+
+ Return a list of failed transactions made by the exchange, typically to a merchant.
+ Since protocol **v4**.
+
+ **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 timeout_ms: *Optional.*
+ Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for at least one element to be shown. Only useful if *limit* is positive.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ JSON object of type `OutgoingFailureHistory`.
+ :http:statuscode:`204 No content`:
+ There are no failures to report (under the given filter).
+ :http:statuscode:`400 Bad request`:
+ Request malformed. The bank replies with an `ErrorDetail` object.
+ :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. The bank replies with an `ErrorDetail` object.
+
+ **Details:**
+
+ .. ts:def:: OutgoingFailureHistory
+
+ interface OutgoingFailureHistory {
+ // Array of outgoing failures.
+ outgoing_failures: OutgoingFailure[];
+
+ // Payto URI to identify the sender of funds.
+ // This must be one of the exchange's bank accounts.
+ // Credit account is shared by all incoming transactions
+ // as per the nature of the request.
+ debit_account: string;
+ }
+
+ .. ts:def:: OutgoingFailure
+
+ interface OutgoingFailure {
+ // Opaque identifier of the returned record.
+ row_id: SafeUint64;
+
+ // Date of the failure.
+ date: Timestamp;
+
+ // Amount transferred.
+ amount: Amount;
+
+ // Payto URI to identify the expected receiver of funds.
+ credit_account: string;
+
+ // The wire transfer ID in the outgoing failure.
+ wtid: ShortHashCode;
+
+ // Base URL of the exchange.
+ exchange_base_url: string;
+
+ // Unstructured messages about the reasons of the failure.
+ reason?: string;
+ }
+
-----------------------
Wire Transfer Test APIs
