taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

api-bank-account-directory.rst (2739B)

      1 ..
      2   This file is part of GNU TALER.
      3 
      4   Copyright (C) 2026 Taler Systems SA
      5 
      6   TALER is free software; you can redistribute it and/or modify it under the
      7   terms of the GNU Affero General Public License as published by the Free Software
      8   Foundation; either version 2.1, or (at your option) any later version.
      9 
     10   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
     11   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     12   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
     13 
     14   You should have received a copy of the GNU Affero General Public License along with
     15   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     16 
     17 ===========================
     18 Taler Account Directory API
     19 ===========================
     20 
     21 This chapter describes the account discovery API that wallets or other clients can use to help the user find their payto URI.
     22 
     23 ---------------
     24 Version History
     25 ---------------
     26 
     27 The current protocol version is **v1**.
     28 
     29 * Nothing depends on the bank account directory API at this point.
     30 
     31 **Version history:**
     32 
     33 * ``v1``: Initial version.
     34 
     35 **Upcoming versions:**
     36 
     37 * None anticipated.
     38 
     39 **Ideas for future version:**
     40 
     41 * ``vXXX``: marker for features not yet targeted for release
     42 
     43 
     44 .. http:get:: /config
     45 
     46   Return the protocol version and configuration information about the bank.
     47 
     48   **Response:**
     49 
     50   :http:statuscode:`200 OK`:
     51     The exchange responds with a `AccountDirectoryConfig` object. This request should
     52     virtually always be successful.
     53 
     54   **Details:**
     55 
     56   .. ts:def:: AccountDirectoryConfig
     57 
     58     interface AccountDirectoryConfig {
     59       // Name of the API.
     60       name: "taler-bank-account-directory";
     61 
     62       // libtool-style representation of the Bank protocol version, see
     63       // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
     64       //
     65       // The format is "current:revision:age".
     66       version: string;
     67 
     68       // URN of the implementation (needed to interpret 'revision' in version).
     69       implementation?: string;
     70     }
     71 
     72 .. http:get:: /search
     73 
     74   Search for user accounts from user query.
     75 
     76   **Request:**
     77 
     78   :query keywords:
     79     Textual search keywords. The fields matched depends on the bank. It can be a name, a login or any other identifier.
     80 
     81   **Response:**
     82 
     83   :http:statuscode:`200 OK`:
     84     Response is a `Accounts`.
     85   :http:statuscode:`204 No content`:
     86     No accounts match this query.
     87 
     88 
     89   **Details:**
     90 
     91   .. ts:def:: Accounts
     92 
     93     interface Accounts {
     94       accounts: Account[];
     95     }
     96 
     97   .. ts:def:: Account
     98 
     99     interface Account {
    100       // Formatted user information to be displayed.
    101       display: string;
    102 
    103       // Full payto URI of this bank account.
    104       payto_uri: string;
    105     }