taler-docs

api-bank-wire-transfer.rst (6769B)

---

 ..
   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.