blob: ad7c4997b29e90cb5b9f0f1092bdf01e4d805168 (
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
160
161
162
163
164
165
166
167
168
169
170
|
..
This file is part of GNU TALER.
Copyright (C) 2014-2024 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 Joel Häberli
===========================
The nonce2ecash RESTful API
===========================
.. note::
**This API is experimental and not yet implemented**
This chapter describe the APIs that third party providers need to integrate to allow
withdrawals through indirect payment channels like credit cards or ATM.
.. contents:: Table of Contents
--------------
Authentication
--------------
Terminals which authenticate against the nonce2ecash API must provide their respective
access token. Therefore they provide a ``Authorization: Bearer $ACCESS_TOKEN`` header,
where `$ACCESS_TOKEN`` is a secret authentication token configured by the exchange and
must begin with the RFC 8959 prefix.
----------------------------
Configuration of nonce2ecash
----------------------------
.. http:get:: /config
Return the protocol version and configuration information about the nonce2ecash API.
**Response:**
:http:statuscode:`200 OK`:
The exchange responds with a `Nonce2ecashConfig` object. This request should
virtually always be successful.
**Details:**
.. ts:def:: Nonce2ecashConfig
interface Nonce2ecashConfig {
// Name of the API.
name: "taler-nonce2ecash";
// libtool-style representation of the nonce2ecash protocol version, see
// https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
// The format is "current:revision:age".
version: string;
}
-----------------------------
Withdrawing using nonce2ecash
-----------------------------
Withdrawals with a nonce2ecash are based on withdrawal operations which register a withdrawal identifier
(nonce) at the nonce2ecash component. The provider must first create a unique identifier for the withdrawal
operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation and eventually withdraw using the wallet.
.. http:post:: /withdrawal-operation
Initiate the withdrawal operation, identified by the ``WITHDRAWAL_ID``.
**Request:**
.. ts:def:: WithdrawRegistration
interface WithdrawRegistration {
// Maps a nonce generated by the provider to a reserve public key generated by the wallet.
withdrawal_id: ShortHashCode;
// Reserve public key generated by the wallet.
// According to TALER_ReservePublicKeyP (https://docs.taler.net/core/api-common.html#cryptographic-primitives)
reserve_pub_key: EddsaPublicKey;
// Optional amount for the withdrawal.
amount?: Amount;
// Id of the terminal of the provider requesting a withdrawal by nonce.
// Assigned by the exchange.
provider_terminal_id: SafeUint64;
}
**Response:**
:http:statuscode:`204 No content`:
The withdrawal was successfully registered.
:http:statuscode:`400 Bad request`:
The ``WithdrawRegistration`` request was malformed or contained invalid parameters.
:http:statuscode:`500 Internal Server error`:
The registration of the withdrawal failed due to server side issues.
.. http:get:: /withdrawal-operation/$WITHDRAWAL_ID
Query information about a withdrawal operation, identified by the ``WITHDRAWAL_ID``.
**Response:**
:http:statuscode:`200 Ok`:
The withdrawal was found and is returned in the response body as ``Withdrawal``.
:http:statuscode:`404 Not found`:
nonce2ecash does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``.
**Details**
.. ts:def:: Withdrawal
interface Withdrawal {
// Reserve public key generated by the wallet.
// According to TALER_ReservePublicKeyP (https://docs.taler.net/core/api-common.html#cryptographic-primitives)
reserve_pub_key: EddsaPublicKey;
// Status of the withdrawal
// pending : the operation is pending parameters selection (exchange and reserve public key)
// selected : the operations has been selected and is pending confirmation
// aborted : the operation has been aborted
// confirmed: the transfer has been confirmed and registered by the bank
withdrawal_status: EddsaPublicKey;
}
.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
Notifies nonce2ecash about an executed payment for a specific withdrawal.
**Request:**
.. ts:def:: PaymentNotification
interface PaymentNotification {
// Unique identifier of the provider transaction.
provider_transaction_id: string;
// Specifies the amount which was payed to the provider (without fees).
// This amount shall be put into the reserve linked to by the withdrawal id.
amount: Amount;
// Fees associated with the payment.
fees: Amount;
}
**Response:**
:http:statuscode:`204 No content`:
nonce2ecash received the ``PaymentNotification`` successfully and will further process
the withdrawal.
:http:statuscode:`400 Bad request`:
The ``PaymentNotification`` request was malformed or contained invalid parameters.
:http:statuscode:`404 Not found`:
nonce2ecash does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``.
:http:statuscode:`500 Internal Server error`:
The ``PaymentNotification`` could not be processed due to server side issues.
|
