commit 1536711db13af21366399bc621592e6e94a866eb
parent 208417836ec964b308e8c840b024bc6286ebc19a
Author: Antoine A <>
Date: Tue, 31 Mar 2026 11:56:08 +0200
wg: improve documentation and add mapping testing endpoint
Diffstat:
1 file changed, 47 insertions(+), 15 deletions(-)
diff --git a/core/api-bank-wire.rst b/core/api-bank-wire.rst
@@ -19,6 +19,17 @@
Taler Wire Gateway HTTP API
===========================
+---------------
+Version History
+---------------
+
+* ``v4``: adds account API.
+* ``v5``: adds metadata and prepared transfer fields
+
+-----------------
+Configuration API
+-----------------
+
This section describes the API offered by the Taler wire adapters. The API is
used by the exchange to trigger transactions and query incoming transactions, as
well as by the auditor to query incoming and outgoing transactions.
@@ -58,6 +69,7 @@ LibEuFin.
implementation?: string;
// Whether implementation support account existence check
+ // @since **v4**
support_account_check: boolean;
}
@@ -669,7 +681,7 @@ exposed by bank gateways in production.
:http:statuscode:`200 OK`:
The request has been correctly handled, so the funds have been transferred to
- the recipient's account. The body is a `AddKycauthResponse`.
+ the recipient's account. The body is a `AddIncomingResponse`.
:http:statuscode:`400 Bad request`:
The request is malformed. The bank replies with an `ErrorDetail` object.
:http:statuscode:`401 Unauthorized`:
@@ -677,25 +689,45 @@ exposed by bank gateways in production.
:http:statuscode:`404 Not found`:
The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
- **Details:**
+.. http:post:: /admin/add-mapped
- .. ts:def:: AddKycauthResponse
+ Simulate a transfer from a customer to the exchange. This API is *not*
+ idempotent since it's only used in testing.
- interface AddKycauthResponse {
- // Timestamp that indicates when the wire transfer will be 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;
+ Since protocol **v5**.
- // Opaque ID of the wire transfer initiation performed by the bank.
- // It is different from the /history endpoints row_id.
- row_id: SafeUint64;
+ **Request:**
+
+ .. ts:def:: AddMappedRequest
+
+ interface AddMappedRequest {
+ // Amount to transfer.
+ amount: Amount;
+
+ // Authorization public key used for registration.
+ authorization_pub: EddsaPublicKey;
+
+ // Account (as full payto URI) that makes the wire transfer to the exchange.
+ // Usually this account must be created by the test harness before this
+ // API is used. An exception is the "fakebank", where any debit account
+ // can be specified, as it is automatically created.
+ debit_account: string;
}
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The request has been correctly handled, so the funds have been transferred to
+ the recipient's account. The body is a `AddIncomingResponse`.
+ :http:statuscode:`400 Bad request`:
+ The request is 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.
+ :http:statuscode:`409 Conflict`:
+ The 'authorization_pub' argument is unknown or have already been used for a non recurrent transfer.
+
Security Considerations
=======================
