-
Notifications
You must be signed in to change notification settings - Fork 2
/
index.html
251 lines (190 loc) · 10.1 KB
/
index.html
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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<!-- <link href='https://fonts.googleapis.com/css?family=Chivo:900' rel='stylesheet' type='text/css'> -->
<link rel="stylesheet" type="text/css" href="stylesheets/stylesheet.css" media="screen" />
<link rel="stylesheet" type="text/css" href="stylesheets/pygment_trac.css" media="screen" />
<link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print" />
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<title>WebWalletAPI by playbanq</title>
</head>
<body>
<div id="container">
<div class="inner">
<header>
<h1>The WebWallet API <br><span> (working draft)</span></h1>
<!-- <h2>A digital wallet specification for the Web</h2> -->
</header>
<hr>
<section id="main_content">
<h1>
<h2>
<a name="abstract" class="anchor" href="#abstract"><span class="octicon octicon-link"></span></a>Abstract</h2>
<p>This specification defines an application programming interface (API) that aims to enable web applications to carry out electronic commerce transactions using WebWallets.</p>
<br>
<h2>
<a name="what-is-a-webwallet" class="anchor" href="#what-is-a-webwallet"><span class="octicon octicon-link"></span></a>What is a WebWallet?</h2>
<p>A WebWallet is a rechargeable digital wallet that can hold electronic money and credentials to make payments on the Web.</p>
<h4>
<a name="features" class="anchor" href="#features"><span class="octicon octicon-link"></span></a>Features</h4>
<ul>
<li><p><strong>No deposits but recharges</strong><br>
A WebWallet is not a deposit account, but a rechargeable digital wallet. Funds are not added as deposits but as prepaid recharges, which represent a temporary intermediation between online buyers and sellers.</p></li>
<li><p><strong>No withdrawals or redemption</strong><br>
A WebWallet recharge is interpreted as a purchase intention, so it cannot be reversed. The funds added to a WebWallet cannot be withdrawn or redeemed for cash, so they must be fully spent at some point.</p></li>
<li><p><strong>No currency exchange</strong><br>
A WebWallet can be recharged in any currency supported by the involved parties and the applicable regulations. However, a WebWallet recharge is not a currency exchange operation by itself.</p></li>
</ul>
<br><h2>
<a name="webwallet-transactions" class="anchor" href="#webwallet-transactions"><span class="octicon octicon-link"></span></a>WebWallet Transactions</h2>
<p>WebWallet transactions are bilateral, token-based and expire if not completed within a certain time interval.</p>
<ul>
<li>
<p><strong>Bilateral</strong> </p>
<ul>
<li>WebWallet transactions are carried out in two major stages: creation and completion.<br>
</li>
<li>Each of the two parties involved must exclusively carry out one of the two stages.<br>
</li>
<li>A transaction initiated by one party can only be completed by the other party.<br>
</li>
</ul>
</li>
<li>
<p><strong>Token-based</strong> </p>
<ul>
<li>WebWallet transactions are initiated by requesting a transaction token to a WebWallet provider.<br>
</li>
<li>Transaction tokens are pointers to information such as the transaction type, amount and currency.<br>
</li>
<li>Tokens must be handed over by the initiator party for the other party to complete the transaction.<br>
</li>
</ul>
</li>
<li>
<p><strong>Expirable</strong> </p>
<ul>
<li>Transaction tokens must have an expiration date and receive a timestamp when they are created.<br>
</li>
<li>Transactions must be completed by the party that did not create the token before the expiration date.<br>
</li>
<li>If a transaction token expires, the initiator party will need to request a new token and start over.<br>
</li>
</ul>
</li>
</ul>
<br><h2>
<a name="webwallet-modules" class="anchor" href="#webwallet-modules"><span class="octicon octicon-link"></span></a>WebWallet Modules</h2>
<p>The WebWallet specification is divided into modules that resemble the different pockets of a physical wallet intended for holding paper money, identification documents, cards and receipts, among others.</p>
<ul>
<li>
<p><strong>Electronic Money</strong><br>
The main goal of a WebWallet is to be as easy to use as a physical wallet: put some money on it, and take some money out to make payments. However, since physical money cannot be literally put into a digital wallet, the funds added to a WebWallet must be reflected as an online balance. </p>
<p><em>"Electronic money is a digital equivalent of cash, stored on an electronic device or remotely at a server."</em> <a href="http://ec.europa.eu/internal_market/payments/emoney/index_en.htm"><em>(European Comission on E-money)</em></a>.</p>
<p>The purpose of the Electronic Money module is to resemble the pocket of a physical wallet that is used for holding paper money, by implementing a digital stored value system whose balance reflects the available funds of a WebWallet that were added through prepaid recharges.</p>
</li>
</ul>
<br><h2>
<a name="api-overview" class="anchor" href="#api-overview"><span class="octicon octicon-link"></span></a>API Overview</h2>
<p>The WebWallet API defines how to expose and interact with WebWallets in order to request and carry out electronic commerce transactions.</p>
<ul>
<li>
<p><strong>Exposure through URIs</strong><br>
Each WebWallet is represented as a URI: </p>
<pre><code>wallet.example.com/:walletID
</code></pre>
</li>
<li>
<p><strong>Secure API calls using tokens</strong><br>
A transaction token must be requested in order to obtain authorization to make API calls:</p>
<pre><code>POST /:walletID/transactions HTTP/1.1
Host: wallet.example.com
options=transaction-options
</code></pre>
</li>
<li>
<p><strong>Transactions through HTTP methods</strong><br>
Transactions are carried out using HTTP methods signed with a valid transaction token.</p>
<p><strong>Checking the balance:</strong></p>
<pre><code>GET /:walletID/balance HTTP/1.1
?token=transaction-token
Host: wallet.example.com
</code></pre>
<p><strong>Adding funds:</strong></p>
<pre><code>POST /:walletID/funds HTTP/1.1
Host: wallet.example.com
token=transaction-token
</code></pre>
<p><strong>Sending/Requesting a payment:</strong></p>
<pre><code>POST /:walletID/payments HTTP/1.1
Host: wallet.example.com
token=transaction-token
</code></pre>
</li>
</ul>
<br><h2>
<a name="webwallet-transaction-flow" class="anchor" href="#webwallet-transaction-flow"><span class="octicon octicon-link"></span></a>WebWallet Transaction Flow</h2>
<h4>
<a name="payments" class="anchor" href="#payments"><span class="octicon octicon-link"></span></a>Payments</h4>
<p>WebWallet payments come in two flavors: user initiated and merchant initiated.</p>
<ul>
<li>
<p><strong>User initiated: merchant charges</strong><br>
When a user initiates a payment transaction, the merchant has to complete it by charging the payment: </p>
<p><strong>1.</strong> The user creates a transaction by requesting a transaction token with the payment information. </p>
<pre><code> POST /:userWalletID/transactions HTTP/1.1
Host: wallet.example.com
options=transaction-options
</code></pre>
<p><strong>2.</strong> The user passes the transaction token to the merchant as an authorization to request the payment. </p>
<pre><code> POST /:merchantWalletID/payments HTTP/1.1
Host: wallet.example.com
token=transaction-token
</code></pre>
<p><strong>3.</strong> The merchant completes the transaction by posting the payment request using the transaction token. </p>
<pre><code> POST /:userWalletID/payments HTTP/1.1
Host: wallet.example.com
token=transaction-token
</code></pre>
<p>By creating and handing over a payment transaction token to a merchant, a user authorizes the merchant to charge the payment to the user's wallet. This is similar to direct debit and credit card charges that are authorized by subscribing recurring payments, swiping a card or filling an online form with its details.</p>
</li>
<li>
<p><strong>Merchant initiated: user pays</strong><br>
When a merchant initiates a payment transaction, the user has to complete it by sending the payment: </p>
<p><strong>1.</strong> The merchant creates a transaction by requesting a transaction token with the payment information. </p>
<pre><code> POST /:merchantWalletID/transactions HTTP/1.1
Host: wallet.example.com
options=transaction-options
</code></pre>
<p><strong>2.</strong> The merchant passes the transaction token to the user as a request or demand to make a payment. </p>
<pre><code> POST /:userWalletID/payments HTTP/1.1
Host: wallet.example.com
token=transaction-token
</code></pre>
<p><strong>3.</strong> The user completes the transaction by posting the payment using the transaction token. </p>
<pre><code> POST /:merchantWalletID/payments HTTP/1.1
Host: wallet.example.com
token=transaction-token
</code></pre>
<p>By creating and handing over a payment transaction token to a user, a merchant requests or demands the user to send the payment to the merchant's wallet. This is similar to cash transactions in which a merchant communicates the payment ammount (e.g. invoice) and waits for the user to hand over the money.</p>
</li>
</ul>
</section>
<hr>
<section id="downloads" class="clearfix">
<!-- <a href="https://github.com/playbanq/WebWalletAPI/zipball/master" id="download-zip" class="button"><span>Download .zip</span></a> -->
<!-- <a href="https://github.com/playbanq/WebWalletAPI/tarball/master" id="download-tar-gz" class="button"><span>Download .tar.gz</span></a> -->
<a href="https://github.com/playbanq/WebWalletAPI" id="view-on-github" class="button"><span>View on GitHub</span></a>
</section>
<footer>
The WebWallet API is maintained by <a href="https://github.com/playbanq">playbanq</a><br>
This page was generated by <a href="http://pages.github.com">GitHub Pages</a>. Tactile theme by <a href="https://twitter.com/jasonlong">Jason Long</a>.
</footer>
</div>
</div>
</body>
</html>