commit 18cb0f93942df6f375c5a1b7418dffcbc208fe0a
parent 240fee00a087f9060a205365356bdf8ae43e3f86
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 8 Jul 2025 18:11:08 +0200
spec where we will go with the merchant API for bug #9454
Diffstat:
| M | core/api-merchant.rst | | | 127 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------- |
1 file changed, 111 insertions(+), 16 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -3666,14 +3666,10 @@ Querying known wire transfers
.. http:get:: [/instances/$INSTANCE]/private/transfers
- Obtain a list of all wire transfers the backend has checked. Note that when
- filtering by timestamp (using ``before`` and/or ``after``), we use the time
- reported by the exchange and thus will ONLY return results for which we already
- have a response from the exchange. This should be virtually all transfers, however
- it is conceivable that for some transfer the exchange responded with a temporary
- error (i.e. HTTP status 500+) and then we do not yet have an execution time to
- filter by. Thus, IF timestamp filters are given, transfers for which we have no
- response from the exchange yet are automatically excluded.
+ Obtain a list of all wire transfers the backend was told
+ had been made into the merchant bank account.
+ Since protocol **vBUG9454** this endpoint is only about
+ actually confirmed wire transfers.
**Required permission:** ``transfers-read``
@@ -3689,7 +3685,7 @@ Querying known wire transfers
:query offset: *Optional*. Starting ``transfer_serial_id`` for an iteration.
- :query verified: *Optional*. Filter transfers by verification status.
+ :query expected: *Optional*. Filter transfers that we expected to receive (YES: only expected, NO: only unexpected, ALL: default). Since protocol **vBUG9454**.
**Response:**
@@ -3725,30 +3721,129 @@ Querying known wire transfers
// Used for filtering via ``offset``.
transfer_serial_id: number;
- // Time of the execution of the wire transfer by the exchange, according to the exchange
- // Only provided if we did get an answer from the exchange.
- execution_time?: Timestamp;
+ // Time of the execution of the wire transfer.
+ execution_time: Timestamp;
// True if we checked the exchange's answer and are happy with it.
// False if we have an answer and are unhappy, missing if we
// do not have an answer from the exchange.
+ // Removed in protocol **vBUG9454**.
verified?: boolean;
// True if the merchant uses the POST /transfers API to confirm
// that this wire transfer took place (and it is thus not
// something merely claimed by the exchange).
+ // Removed in protocol **vBUG9454**.
confirmed?: boolean;
+
+ // True if this wire transfer was expected.
+ // (a matching "/private/incoming" record exists).
+ // Since protocol **vBUG9454**.
+ expected?: boolean;
}
-Deleting wire transfer
-----------------------
+
+Querying expected wire transfers
+--------------------------------
+
+.. http:get:: [/instances/$INSTANCE]/private/incoming
+
+ Obtain a list of expected incoming wire transfers the backend is
+ anticipating.
+ Since protocol **vBUG9454**.
+
+ **Required permission:** ``transfers-read``
+
+ **Request:**
+
+ :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.
+
+ :query before: *Optional*. Filter for transfers executed before the given timestamp.
+
+ :query after: *Optional*. Filter for transfers executed after the given timestamp.
+
+ :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``.
+
+ :query offset: *Optional*. Starting ``transfer_serial_id`` for an iteration.
+
+ :query verified: *Optional*. Filter transfers by verification status (YES: reconcilation worked, NO: reconciliation failed, ALL: default)
+
+ :query confirmed: *Optional*. Filter transfers that were confirmed (YES: credit confirmed, NO: credit still pending, ALL: default)
+
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The body of the response is a `ExpectedTransferList`.
+
+ **Details:**
+
+ .. ts:def:: ExpectedTransferList
+
+ interface ExpectedTransferList {
+ // List of all the expected incoming transfers that fit the
+ // filter that we know.
+ incoming : ExpectedTransferDetails[];
+ }
+
+ .. ts:def:: ExpectedTransferDetails
+
+ interface TransferDetails {
+ // How much should be wired to the merchant (minus fees).
+ expected_credit_amount?: Amount;
+
+ // Raw wire transfer identifier identifying the wire transfer (a base32-encoded value).
+ wtid: WireTransferIdentifierRawP;
+
+ // Full payto://-URI of the bank account that received the wire transfer.
+ payto_uri: string;
+
+ // Base URL of the exchange that made the wire transfer.
+ exchange_url: string;
+
+ // Serial number identifying the expected transfer in the backend.
+ // Used for filtering via ``offset``.
+ expected_transfer_serial_id: number;
+
+ // Expected time of the execution of the wire transfer
+ // by the exchange, according to the exchange.
+ execution_time: Timestamp;
+
+ // True if we checked the exchange's answer and are happy with
+ // the reconciation data.
+ // False if we have an answer and are unhappy, missing if we
+ // do not have an answer from the exchange.
+ // Does not imply that the wire transfer was settled (for
+ // that, see ``confirmed``).
+ verified: boolean;
+
+ // True if the merchant uses the POST /transfers API to confirm
+ // that this wire transfer took place (and it is thus not
+ // something merely claimed by the exchange).
+ // (a matching entry exists in /private/transfers)
+ confirmed: boolean;
+
+ // Last HTTP status we received from the exchange, 0 for
+ // none (incl. timeout)
+ last_http_status: number;
+
+ // Last Taler error code we got from the exchange.
+ last_ec: ErrorCode;
+
+ // Last error detail we got back from the exchange.
+ last_error_detail?: string;
+ }
+
+
+Deleting confirmed wire transfer
+--------------------------------
Deleting a wire transfer can be useful in case of a data entry
mistake. In particular, if the exchange base URL was entered
badly, deleting the old entry and adding a correct one is a
-good idea. Note that deleting wire transfers is no longer possible
-once we got a reply from the exchange.
+good idea. Note that deleting wire transfers is not possible
+if they were expected.
.. http:delete:: [/instances/$INSTANCE]/private/transfers/$TID
