commit 9cbd16d99c8b2c89c1203fed96882a63440a4d07
parent 143efe7dbe36c5fb518a86c62283d0f69f206e31
Author: Antoine A <>
Date: Tue, 31 Mar 2026 11:30:10 +0200
corebank: rename Taler Wire Transfer Gateway to Taler Prepared Transfer
Diffstat:
4 files changed, 229 insertions(+), 229 deletions(-)
diff --git a/core/api-bank-transfer.rst b/core/api-bank-transfer.rst
@@ -0,0 +1,226 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2026 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+.. _taler-wire-transfer-gateway-http-api:
+
+================================
+Taler Prepared Transfer HTTP API
+================================
+
+This section describes the API offered by Taler wire adapters. The API is
+used by clients such as wallets to prepare wire transfers. This allows the use
+of wire-specific subject format or optimized alternating wire transfer flows,
+and enables the use of recurring wire transfers.
+
+.. http:get:: /config
+
+ Return the protocol version and configuration information about the bank.
+ This specification corresponds to ``current`` protocol being version **1**.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The adapter responds with a `WireTransferConfig` object. This request
+ should virtually always be successful.
+
+ **Details:**
+
+ .. ts:def:: SubjectFormat
+
+ type SubjectFormat =
+ | "SIMPLE"
+ | "URI"
+ | "CH_QR_BILL";
+
+ .. ts:def:: WireTransferConfig
+
+ interface WireTransferConfig {
+ // Name of the API.
+ name: "taler-prepared-transfer";
+
+ // libtool-style representation of the Bank protocol version, see
+ // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
+ // The format is "current:revision:age".
+ version: string;
+
+ // Currency used by this gateway.
+ currency: string;
+
+ // URN of the implementation (needed to interpret 'revision' in version).
+ // @since v0, may become mandatory in the future.
+ implementation?: string;
+
+ // Supported formats for registration, there must at least one.
+ supported_formats: SubjectFormat[];
+ }
+
+-----------------------
+Prepared wire transfers
+-----------------------
+
+.. http:post:: /registration
+
+ Register a public key for wire transfer use.
+
+ This endpoint generate appropriate subjects to link a transfer to the
+ registered public key.
+
+ Two public keys must be provided, the ``account_pub`` key is the key that
+ will forwarded to the exchange and the ``authorization_pub`` key will be
+ encoded inside the subject.
+
+ For simple one time wire transfers, use the same key for both ``account_pub``
+ and ``authorization_pub``. For recurrent transfers, use a single
+ ``authorization_pub`` for different ``account_pub``.
+
+ If registered as ``recurrent`` the wire adapters will keep incoming transfers
+ reusing the same subject until a registration is performed, else it will
+ bounce.
+
+ Registration with the same ``authorization_pu`` will replace the existing information registered for the key.
+
+ **Request:**
+
+ .. ts:def:: RegistrationRequest
+
+ interface RegistrationRequest {
+ // Amount to transfer
+ credit_amount: Amount;
+
+ // Transfer types
+ type: "reserve" | "kyc";
+
+ // Public key algorithm
+ alg: "EdDSA";
+
+ // Account public key for the exchange
+ account_pub: EddsaPublicKey;
+
+ // Public key encoded inside the subject
+ authorization_pub: EddsaPublicKey;
+
+ // Signature of the account_pub key using the authorization_pub private key
+ authorization_sig: EddsaSignature;
+
+ // Whether the authorization_pub will be reused for recurrent transfers
+ // Disable bounces in case of authorization_pub reuse
+ recurrent: boolean;
+ }
+
+ **Response:**
+
+ :http:statuscode:`200 Ok`:
+ Response is a `RegistrationResponse`.
+ :http:statuscode:`400 Bad request`:
+ Input data was invalid.
+ :http:statuscode:`409 Conflict`:
+ * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT``: the same reserve public key is already registered, you should retry using another key.
+ * ``TALER_EC_BANK_DERIVATION_REUSE``: derived subject is already used, you should retry using another key.
+ * ``TALER_EC_BANK_BAD_SIGNATURE``: signature is invalid.
+
+ **Details:**
+
+ .. ts:def:: TransferSubject
+
+ // Union discriminated by the "type" field.
+ type TransferSubject =
+ | SimpleSubject
+ | UriSubject
+ | SwissQrBillSubject;
+
+ .. ts:def:: SimpleSubject
+
+ interface SimpleSubject {
+ // Subject for system accepting large subjects
+ type: "SIMPLE";
+
+ // Amount to transfer
+ credit_amount: Amount;
+
+ // Encoded string containing either the full key and transfer type or a
+ // derived short subject
+ subject: string;
+ }
+
+ .. ts:def:: UriSubject
+
+ interface UriSubject {
+ // Subject for system accepting prepared payments
+ type: "URI";
+
+ // Amount to transfer
+ credit_amount: Amount;
+
+ // Prepared payments confirmation URI
+ uri: string;
+ }
+
+ .. ts:def:: SwissQrBillSubject
+
+ interface SwissQrBillSubject {
+ // Subject for Swiss QR Bill
+ type: "CH_QR_BILL";
+
+ // Amount to transfer
+ credit_amount: Amount;
+
+ // 27-digit QR Reference number
+ qr_reference_number: string;
+ }
+
+ .. ts:def:: RegistrationResponse
+
+ interface RegistrationResponse {
+ // The transfer subject encoded in all supported formats
+ subjects: TransferSubject[];
+
+ // Expiration date after which this subject is expected to be reused
+ expiration: Timestamp;
+ }
+
+.. http:delete:: /registration
+
+ Remove an existing registered public key for wire transfer use.
+
+ Use this endpoint to free a derived subject or cancel a recurrent paiment.
+
+
+ **Request:**
+
+ .. ts:def:: Unregistration
+
+ interface Unregistration {
+ // Current timestamp in the ISO 8601
+ timestamp: string;
+
+ // Public key used for registration
+ authorization_pub: EddsaPublicKey;
+
+ // Signature of the timestamp using the authorization_pub private key
+ // Prevent replay attack
+ authorization_sig: EddsaSignature;
+ }
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ The registration have been deleted.
+ :http:statuscode:`400 Bad request`:
+ Input data was invalid.
+ :http:statuscode:`404 Not found`:
+ Unknown registration.
+ :http:statuscode:`409 Conflict`:
+ * ``TALER_EC_BANK_OLD_TIMESTAMP``: the timestamp is too old.
+ * ``TALER_EC_BANK_BAD_SIGNATURE``: signature is invalid.
+\ No newline at end of file
diff --git a/core/api-bank-wire-transfer.rst b/core/api-bank-wire-transfer.rst
@@ -1,226 +0,0 @@
-..
- This file is part of GNU TALER.
- Copyright (C) 2026 Taler Systems SA
-
- TALER is free software; you can redistribute it and/or modify it under the
- terms of the GNU Affero General Public License as published by the Free Software
- Foundation; either version 2.1, or (at your option) any later version.
-
- TALER is distributed in the hope that it will be useful, but WITHOUT ANY
- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
- A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-
- You should have received a copy of the GNU Affero General Public License along with
- TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-
-.. _taler-wire-transfer-gateway-http-api:
-
-====================================
-Taler Wire Transfer Gateway HTTP API
-====================================
-
-This section describes the API offered by Taler wire adapters. The API is
-used by clients such as wallets to prepare wire transfers. This allows the use
-of wire-specific subject format or optimized alternating wire transfer flows,
-and enables the use of recurring wire transfers.
-
-.. http:get:: /config
-
- Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being version **1**.
-
- **Response:**
-
- :http:statuscode:`200 OK`:
- The adapter responds with a `WireTransferConfig` object. This request
- should virtually always be successful.
-
- **Details:**
-
- .. ts:def:: SubjectFormat
-
- type SubjectFormat =
- | "SIMPLE"
- | "URI"
- | "CH_QR_BILL";
-
- .. ts:def:: WireTransferConfig
-
- interface WireTransferConfig {
- // Name of the API.
- name: "taler-wire-transfer-gateway";
-
- // libtool-style representation of the Bank protocol version, see
- // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
- // The format is "current:revision:age".
- version: string;
-
- // Currency used by this gateway.
- currency: string;
-
- // URN of the implementation (needed to interpret 'revision' in version).
- // @since v0, may become mandatory in the future.
- implementation?: string;
-
- // Supported formats for registration, there must at least one.
- supported_formats: SubjectFormat[];
- }
-
------------------------
-Prepared wire transfers
------------------------
-
-.. http:post:: /registration
-
- Register a public key for wire transfer use.
-
- This endpoint generate appropriate subjects to link a transfer to the
- registered public key.
-
- Two public keys must be provided, the ``account_pub`` key is the key that
- will forwarded to the exchange and the ``authorization_pub`` key will be
- encoded inside the subject.
-
- For simple one time wire transfers, use the same key for both ``account_pub``
- and ``authorization_pub``. For recurrent transfers, use a single
- ``authorization_pub`` for different ``account_pub``.
-
- If registered as ``recurrent`` the wire adapters will keep incoming transfers
- reusing the same subject until a registration is performed, else it will
- bounce.
-
- Registration with the same ``authorization_pu`` will replace the existing information registered for the key.
-
- **Request:**
-
- .. ts:def:: RegistrationRequest
-
- interface RegistrationRequest {
- // Amount to transfer
- credit_amount: Amount;
-
- // Transfer types
- type: "reserve" | "kyc";
-
- // Public key algorithm
- alg: "EdDSA";
-
- // Account public key for the exchange
- account_pub: EddsaPublicKey;
-
- // Public key encoded inside the subject
- authorization_pub: EddsaPublicKey;
-
- // Signature of the account_pub key using the authorization_pub private key
- authorization_sig: EddsaSignature;
-
- // Whether the authorization_pub will be reused for recurrent transfers
- // Disable bounces in case of authorization_pub reuse
- recurrent: boolean;
- }
-
- **Response:**
-
- :http:statuscode:`200 Ok`:
- Response is a `RegistrationResponse`.
- :http:statuscode:`400 Bad request`:
- Input data was invalid.
- :http:statuscode:`409 Conflict`:
- * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT``: the same reserve public key is already registered, you should retry using another key.
- * ``TALER_EC_BANK_DERIVATION_REUSE``: derived subject is already used, you should retry using another key.
- * ``TALER_EC_BANK_BAD_SIGNATURE``: signature is invalid.
-
- **Details:**
-
- .. ts:def:: TransferSubject
-
- // Union discriminated by the "type" field.
- type TransferSubject =
- | SimpleSubject
- | UriSubject
- | SwissQrBillSubject;
-
- .. ts:def:: SimpleSubject
-
- interface SimpleSubject {
- // Subject for system accepting large subjects
- type: "SIMPLE";
-
- // Amount to transfer
- credit_amount: Amount;
-
- // Encoded string containing either the full key and transfer type or a
- // derived short subject
- subject: string;
- }
-
- .. ts:def:: UriSubject
-
- interface UriSubject {
- // Subject for system accepting prepared payments
- type: "URI";
-
- // Amount to transfer
- credit_amount: Amount;
-
- // Prepared payments confirmation URI
- uri: string;
- }
-
- .. ts:def:: SwissQrBillSubject
-
- interface SwissQrBillSubject {
- // Subject for Swiss QR Bill
- type: "CH_QR_BILL";
-
- // Amount to transfer
- credit_amount: Amount;
-
- // 27-digit QR Reference number
- qr_reference_number: string;
- }
-
- .. ts:def:: RegistrationResponse
-
- interface RegistrationResponse {
- // The transfer subject encoded in all supported formats
- subjects: TransferSubject[];
-
- // Expiration date after which this subject is expected to be reused
- expiration: Timestamp;
- }
-
-.. http:delete:: /registration
-
- Remove an existing registered public key for wire transfer use.
-
- Use this endpoint to free a derived subject or cancel a recurrent paiment.
-
-
- **Request:**
-
- .. ts:def:: Unregistration
-
- interface Unregistration {
- // Current timestamp in the ISO 8601
- timestamp: string;
-
- // Public key used for registration
- authorization_pub: EddsaPublicKey;
-
- // Signature of the timestamp using the authorization_pub private key
- // Prevent replay attack
- authorization_sig: EddsaSignature;
- }
-
- **Response:**
-
- :http:statuscode:`204 No content`:
- The registration have been deleted.
- :http:statuscode:`400 Bad request`:
- Input data was invalid.
- :http:statuscode:`404 Not found`:
- Unknown registration.
- :http:statuscode:`409 Conflict`:
- * ``TALER_EC_BANK_OLD_TIMESTAMP``: the timestamp is too old.
- * ``TALER_EC_BANK_BAD_SIGNATURE``: signature is invalid.
-\ No newline at end of file
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -1888,7 +1888,7 @@ Endpoints for Integrated Sub-APIs
Since **v12**
All endpoints under this prefix are specified
- by the :doc:`GNU Taler wire transfer gateway API </core/api-bank-wire-transfer>`.
+ by the :doc:`GNU Taler prepared transfer API </core/api-bank-transfer>`.
The endpoints are only available for accounts configured with ``is_taler_exchange=true``.
diff --git a/core/index-bank-apis.rst b/core/index-bank-apis.rst
@@ -30,7 +30,7 @@ Bank RESTful APIs
intro-bank-apis
api-corebank
api-bank-wire
- api-bank-wire-transfer
+ api-bank-transfer
api-bank-revenue
api-bank-integration
api-bank-conversion-info
