summaryrefslogtreecommitdiff
path: root/core/api-bank-integration.rst
blob: 298e3d75e9b9d6b435ce7ab832735cb695e56f66 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
..
  This file is part of GNU TALER.

  Copyright (C) 2014-2020 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/>

  @author Marcello Stanisci
  @author Christian Grothoff

==========================
Taler Bank Integration API
==========================

This chapter describe the APIs that banks need to offer towards Taler wallets
to tightly integrate with GNU Taler.

.. contents:: Table of Contents

.. http:get:: /config

  Get configuration information about the bank.

  **Request:**

  **Response:**

  :http:statuscode:`200 OK`:
    The exchange responds with a `BankVersion` object. This request should
    virtually always be successful.

  **Details:**

  .. ts:def:: BankVersion

    interface BankVersion {
      // 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 bank.
      currency: string;

      // Name of the API.
      name: "taler-bank-integration";
    }


-----------
Withdrawing
-----------

Withdrawals with a Taler-integrated bank are based on withdrawal operations.
Some user interaction (on the bank's website or a Taler-enabled ATM) creates a
withdrawal operation record in the bank's database.  The wallet can use a unique identifier
for the withdrawal operation (the ``wopid``) to interact with the withdrawal operation.

.. http:get:: ${BANK_API_BASE_URL}/withdrawal-operation/${wopid}

  Query information about a withdrawal operation, identified by the ``wopid``.

  **Request**

  :query long_poll_ms:
    *Optional.*  If specified, the bank will wait up to ``long_poll_ms``
    milliseconds for completion of the transfer before sending the HTTP
    response.  A client must never rely on this behavior, as the bank may
    return a response immediately.

  **Response**

  :http:statuscode:`200 OK`:
    The withdrawal operation is known to the bank, and details are given
    in the `BankWithdrawalOperationStatus` response body.


  .. ts:def:: BankWithdrawalOperationStatus

    export class BankWithdrawalOperationStatus {
      // Has the wallet selected parameters for the withdrawal operation
      // (exchange and reserve public key) and successfully sent it
      // to the bank?
      selection_done: boolean;

      // The transfer has been confirmed and registered by the bank.
      // Does not guarantee that the funds have arrived at the exchange already.
      transfer_done: boolean;

      // Amount that will be withdrawn with this operation
      // (raw amount without fee considerations).
      amount: Amount;

      // Bank account of the customer that is withdrawing, as a
      // ``payto`` URI.
      sender_wire?: string;

      // Suggestion for an exchange given by the bank.
      suggested_exchange?: string;

      // URL that the user needs to navigate to in order to
      // complete some final confirmation (e.g. 2FA).
      confirm_transfer_url?: string;

      // Wire transfer types supported by the bank.
      wire_types: string[];
    }

.. http:post:: ${BANK_API_BASE_URL}/withdrawal-operation/${wopid}

  **Request** The body of this request must have the format of a `BankWithdrawalOperationPostRequest`.

  **Response**

  :http:statuscode:`200 OK`:
    The bank has accepted the withdrawal operation parameters chosen by the wallet.
    The response is a `BankWithdrawalOperationPostResponse`.
  :http:statuscode:`404 Not found`:
    The bank does not know about a withdrawal operation with the specified ``wopid``.

  **Details**

  .. ts:def:: BankWithdrawalOperationPostRequest

    interface BankWithdrawalOperationPostRequest {

      // Reserve public key.
      reserve_pub: string;

      // Exchange bank details specified in the ``payto``
      // format.  NOTE: this field is optional, therefore
      // the bank will initiate the withdrawal with the
      // default exchange, if not given.
      exchange_wire_details: string;
    }

  .. ts:def:: BankWithdrawalOperationPostResponse

    interface BankWithdrawalOperationPostResponse {

      // The transfer has been confirmed and registered by the bank.
      // Does not guarantee that the funds have arrived at the exchange already.
      transfer_done: boolean;

      // URL that the user needs to navigate to in order to
      // complete some final confirmation (e.g. 2FA).
      //
      // Only applicable when ``transfer_done`` is ``false``.
      confirm_transfer_url?: string;
    }