blob: 030b961a2dc9a75b6c2c54c1ca2e67757bd4b460 (
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
171
172
173
174
175
176
177
178
179
180
181
|
..
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 C2EC 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 C2EC 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 C2EC
----------------------------
.. http:get:: /config
Return the protocol version and configuration information about the C2EC API.
**Response:**
:http:statuscode:`200 OK`:
The exchange responds with a `C2ECConfig` object. This request should
virtually always be successful.
**Details:**
.. ts:def:: C2ECConfig
interface C2ECConfig {
// Name of the API.
name: "taler-c2ec";
// libtool-style representation of the C2EC 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 C2EC
-----------------------------
Withdrawals with a C2EC are based on withdrawal operations which register a withdrawal identifier
(nonce) at the C2EC 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:: C2ECWithdrawalOperationPostRequest
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 ``C2ECWithdrawalStatus``.
:http:statuscode:`404 Not found`:
C2EC does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``.
**Details**
.. ts:def:: C2ECWithdrawalStatus
interface C2ECWithdrawalStatus {
// Current status of the operation
// 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
// Since protocol v1.
status: "pending" | "selected" | "aborted" | "confirmed";
// Amount that will be withdrawn with this operation
// (raw amount without fee considerations).
amount: Amount;
// A refund address as ``payto`` URI. This address shall be used
// in case a refund must be done. Only not-null if the status
// is "confirmed" or "aborted"
refund_wire?: string;
// Reserve public key selected by the exchange,
// only non-null if ``status`` is ``selected`` or ``confirmed``.
// Since protocol v1.
selected_reserve_pub?: string;
}
.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
Notifies C2EC about an executed payment for a specific withdrawal.
**Request:**
.. ts:def:: C2ECPaymentNotification
interface C2ECPaymentNotification {
// 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`:
C2EC received the ``C2ECPaymentNotification`` successfully and will further process
the withdrawal.
:http:statuscode:`400 Bad request`:
The ``C2ECPaymentNotification`` request was malformed or contained invalid parameters.
:http:statuscode:`404 Not found`:
C2EC does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``.
:http:statuscode:`500 Internal Server error`:
The ``C2ECPaymentNotification`` could not be processed due to server side issues.
|
