summaryrefslogtreecommitdiff
path: root/doc/manual.texi
blob: 228d897e70623aa179a602deb3e8d8bd49b30834 (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
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
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename manual.info
@include version.texi
@settitle The GNU Taler manual for Web shop operators @value{VERSION}

@c Define a new index for options.
@defcodeindex op
@c Combine everything into one index (arbitrarily chosen to be the
@c concept index).
@syncodeindex op cp
@c %**end of header

@copying
This manual is for the GNU Taler merchant backend (version @value{VERSION}, @value{UPDATED}),

Copyright @copyright{} 2016 INRIA

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying
@c If your manual is published on paper by the FSF, it should include
@c The standard FSF Front-Cover and Back-Cover Texts, as given in
@c maintain.texi.
@c
@c Titlepage
@c
@titlepage
@title The GNU Taler manual for Web shops
@subtitle Version @value{VERSION}
@subtitle @value{UPDATED}
@author Marcello Stanisci (@email{marcello.stanisci@@inria.fr})
@author Christian Grothoff (@email{christian.grothoff@@inria.fr})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@summarycontents
@contents

@ifnottex
@node Top
@top The GNU Taler manual for Web shops
@insertcopying
@end ifnottex

@menu
* Introduction::            Whom this manual is addressed to
* Installation::            Installing the Merchant backend
* Configuration::           How to set up the Merchant backend
* Hello-world::             How to set up a minimalistic shop
* Back-office-integration:: How to integrate with the back office
@end menu


@node Introduction
@chapter Introduction

@section About GNU Taler

GNU Taler is an open protocol for an electronic payment system with a
free software reference implementation.  GNU Taler offers secure, fast
and easy payment processing using well understood cryptographic
techniques.  GNU Taler allows customers to remain anonymous, while
ensuring that merchants can be held accountable by governments.
Hence, GNU Taler is compatible with anti-money-laundering (AML) and
know-your-customer (KYC) regulation, as well as data protection
regulation (such as GDPR).

@section About this manual

This manual addresses how to integrate GNU Taler with Web shops.  It
describes how to install a GNU Taler merchant @emph{backend} and how
to integrate it with an existing Web shop @emph{frontend}.

The manual is for system administrators and Web developers.  We expect
some moderate familiarity with the compilation and installation of free
software packages and of Web technology, in particular HTML and HTTP.
An understanding of cryptography is not required.

You can download all of the code examples given in this tutorial from
@url{https://git.taler.net/merchant.git/tree/doc/examples/}.


@section Architecture overview

The Taler software stack for a merchant consists of four main components:

@itemize
@item A frontend which interacts with the customer's browser. The
  frontend enables the customer to build a shopping cart and place
  an order.  Upon payment, it triggers the respective business logic
  to satisfy the order.  This component is not included with Taler,
  but rather assumed to exist at the merchant. This manual will
  describe how to integrate Taler with Web shop frontends.
@item A back office application that enables the shop operators to
  view customer orders, match them to financial transfers, and possibly
  approve refunds if an order cannot be satisfied.  This component is
  again not included with Taler, but rather assumed to exist at the
  merchant. This manual will describe how to integrate such a component
  to handle payments managed by Taler.
@item A Taler-specific payment backend which makes it easy for the
  frontend to process financial transactions with Taler.  The
  next two chapters will describe how to install and configure
  this backend.
@item A DBMS which stores the transaction history for the Taler backend.
  For now, the GNU Taler reference implemenation only supports Postgres,
  but the code could be easily extended to support another DBMS. This
  manual assumes that a reasonably recent Postgres installation (@math{\ge 9.5})
  exists on the target system.
@end itemize

The following image illustrates the various interactions of these
key components:

@center @image{arch, 3in, 4in}


Basically, the backend provides the cryptographic protocol support,
stores Taler-specific financial information in a DBMS and communicates
with the GNU Taler exchange over the Internet.  The frontend accesses
the backend via a RESTful API.  As a result, the frontend never has to
directly communicate with the exchange, and also does not deal with
sensitive data.  In particular, the merchant's signing keys and bank
account information is encapsulated within the Taler backend.


@node Installation
@menu
* generic-instructions:: Generic installation guidelines
@c * Installing Taler with GNU Guix:: Installing Taler with GNU Guix
@c * Installing Taler using Docker:: Installing Taler using Docker
@c * Installing Taler on Debian GNU/Linux:: Installing Taler on Debian GNU/Linux
@c * Installing Taler on Arch Linux:: Installing Taler on Arch Linux
@c * Installing Taler on Windows:: Installing Taler on Windows
@c * Installing Taler on OS X:: Installing Taler on OS X
@end menu

@chapter Installation

This chapter describes how to install the GNU Taler merchant backend.

@node generic-instructions
@section Generic instructions

This section provides generic instructions for the merchant
backend installation independent of any particular operating system.
@c Operating system specific instructions are provided in the following sections.
@c You should follow the operating system specific instructions if those are available, and only consult the generic instructions if no system-specific instructions are provided for your specific operating system.

@node dependencies
@subsection Installation of dependencies

The following packages need to be installed before we can compile the
backend:

@itemize
@item libcurl or libgnurl
@item GNU libmicrohttpd, including GnuTLS
@item GNU libgcrypt
@item libjansson
@item Postgres, including libpq
@item GNUnet
@item GNU Taler exchange
@end itemize

The first five are available in most GNU/Linux distributions and should
just be installed using the respective package manager, for example
using

@example
# apt-get install libcurl4-gnutls-dev \
  libmicrohttpd-dev \
  libgnutls-dev \
  libgcrypt20-dev \
  libjansson-dev \
  libpq-dev \
  postgresql-9.5
@end example

The following sections will provide detailed instructions for
installing the GNUnet and GNU Taler exchange dependencies.


@subsection Installing GNUnet

Note that a Web shop supporting GNU Taler does not actually need to run a
GNUnet peer.  The requirement to have a minimal GNUnet installation
arises from the fact that GNUnet provides some required routines for
doing cryptography, string manupulation, interfacing with databases,
JSON manipulation, logging and operating system abstractions.  Hence
this manual does not describe how to actually run a GNUnet peer, and
we also skip optional GNUnet dependencies that an ordinary peer might
want to include in the installation.  Thus, do not be alarmed if the
GNUnet build process warns you about missing (optional) dependencies.

Before you install GNUnet, you should download and install the
dependencies mentioned in the previous section, otherwise GNUnet may
install but fail to export some of the tooling required by Taler.

To download and install GNUnet, proceed as follows:

@example
$ svn checkout https://gnunet.org/svn/gnunet/
$ cd gnunet/
$ ./bootstrap
$ ./configure [--prefix=GNUNETPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-<LIBNAME>' option. See './configure --help'.
$ make
# make install
@end example

If you did not specify a prefix, GNUnet will install to
@code{/usr/local}, which requires you to run the last step as
@code{root}.

@subsection Installing the GNU Taler exchange

After installing GNUnet, you can download and install
the exchange as follows:

@example
$ git clone git://taler.net/exchange
$ cd exchange
$ ./bootstrap
$ ./configure [--prefix=EXCHANGEPFX] \
              [--with-gnunet=GNUNETPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-<LIBNAME>' option. See './configure --help'.
$ make
# make install
@end example

If you did not specify a prefix, the exchange will install to
@code{/usr/local}, which requires you to run the last step as
@code{root}.  Note that you have to specify
@code{--with-gnunet=/usr/local} if you installed GNUnet to
@code{/usr/local} in the previous step.


@subsection Installing the GNU Taler merchant backend

The following steps assume all dependencies are installed.

Use the following commands to download and install the
merchant backend:

@example
$ git clone git://taler.net/merchant
$ cd merchant
$ ./bootstrap
$ ./configure [--prefix=PFX] \
              [--with-gnunet=GNUNETPFX] \
              [--with-exchange=EXCHANGEPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-<LIBNAME>' option. See './configure --help'.
$ make
$ make install
@end example

Note that you have to specify @code{--with-exchange=/usr/local} and/or
@code{--with-exchange=/usr/local} if you installed the exchange and/or
GNUnet to @code{/usr/local} in the previous steps.

@c @node Installing Taler with GNU Guix
@c @section Installing Taler with GNU Guix

@c This section has not yet been written.


@c @node Installing Taler using Docker
@c @section Installing Taler using Docker

@c This section has not yet been written.


@c @node Installing Taler on Debian GNU/Linux
@c @section Installing Taler on Debian GNU/Linux

@c This section has not yet been written.


@c @node Installing Taler on Arch Linux
@c @section Installing Taler on Arch Linux

@c This section has not yet been written.


@c @node Installing Taler on Windows
@c @section Installing Taler on Windows

@c This section has not yet been written.


@c @node Installing Taler on OS X
@c @section Installing Taler on OS X

@c This section has not yet been written.



@node Configuration
@chapter How to configure the merchant's backend

The installation already provides reasonable defaults for most of the
configuration options. However, some must be provided, in particular
the database account and bank account that the backend should use.  By
default, the file @code{$HOME/.config/taler.conf} is where the Web
shop administrator specifies configuration values that augment or
override the defaults.

@section Using taler-config

The tool @code{taler-config} can be used to
extract or manipulate configuration values; however, the configuration
use the well-known INI file format and can also be edited by hand.

Run
@example
$ taler-config -s $SECTION
@end example
to list all of the configuration values in section @code{$SECTION}.

Run
@example
$ taler-config -s $section -o $option
@end example
to extract the respective configuration value for option @code{$option}
in section @code{$section}.

Finally, to change a setting, run
@example
$ taler-config -s $section -o $option -V $value
@end example
to set the respective configuration value to @code{$value}. Note that you have to
manually restart the Taler backend after you change the configuration to
make the new configuration go into effect.

Some default options will use $-variables, such as @code{$DATADIR}
within their value.  To expand the @code{$DATADIR} or other $-variables
in the configuration, pass the @code{-f} option to
@code{taler-config}.  For example, compare:
@example
$ taler-config -s merchant-instance-wireformat-default \
               -o test_response_file
$ taler-config -f -s merchant-instance-wireformat-default \
               -o test_response_file
@end example

While the configuration file is typically located at
@code{$HOME/.config/taler.conf}, an alternative location can be
specified to @code{taler-merchant-httpd} and @code{taler-config} using
the @code{-c} option.


@section Backend options

The following table describes the options that commonly need to be modified.
Here, the notation @code{[$section]/$option} denotes the option
@code{$option} under the section @code{[$section]} in the configuration file.


@table @asis

@item Service address
The following option sets the transport layer address used by the Merchant backend:

@example
[merchant]/serve = TCP | UNIX
@end example

If given,
@itemize
@item @code{TCP}, then we need to set the TCP port in @code{[merchant]/port}
@item @code{UNIX}, then we need to set the unix domain socket path and mode in
@code{[merchant]/unixpath} and @code{[merchant]/unixpath_mode}. The latter takes
the usual permission mask given as a number, e.g. 660 for user/group read-write access.
@end itemize

The frontend can then connect to the backend over HTTP using the specified address.
If frontend and backend run within the same operating system, the use of
a UNIX domain socket is recommended to avoid accidentally exposing the backend
to the network.

@c FIXME: we should offer an option to bind the TCP socket to a particular IP address (#4752)

To run the Taler backend on TCP port 8888, use:
@example
$ taler-config -s merchant -o serve -V TCP
$ taler-config -s merchant -o port -V 8888
@end example


@item Currency
Which currency the Web shop deals in, i.e. ``EUR'' or ``USD'', is specified using the option

@example
[merchant]/currency
@end example

For testing purposes, the currency should match ``KUDOS'' which is used by the Taler
demonstration exchange at @url{https://exchange.demo.taler.net/}:

@example
$ taler-config -s merchant -o currency -V KUDOS
@end example


@item Database
In principle is possible for the backend to support different DBMSs.
The option

@example
[merchant]/db
@end example

specifies which DBMS is to be used. However, currently only the value "postgres" is supported. This is also
the default.

In addition to selecting the DBMS software, the backend requires DBMS-specific options to access the database.

For postgres, you need to provide:

@example
[merchantdb-postgres]/config
@end example

This option specifies a postgres access path using the format
@code{postgres:///$DBNAME}, where @code{$DBNAME} is the name of the Postgres
database you want to use.  Suppose @code{$USER} is the name of the
user who will run the backend process.  Then, you need to first run

@example
$ createuser -d $USER
@end example

as the @code{postgres} database administrator to grant @code{$USER}
the ability to create new databases.  Next, you should as
@code{$USER} run

@example
$ createdb $DBNAME
@end example

to create the backend's database.  Here, @code{$DBNAME} must match the database name
given in the configuration file.

To configure the Taler backend to use this database, run:
@example
$ taler-config -s merchantdb-postgres -o config \
  -V postgres:///$DBNAME
@end example


@item Exchange
To add an exchange to the list of trusted payment service providers,
you create a section with a name that starts with ``merchant-exchange-''.
In that section, the following options need to be configured:

@itemize

@item
The ``uri'' option specifies the exchange's base URL.  For example,
to use the Taler demonstrator use:

@example
$ taler-config -s merchant-exchange-demo -o config \
  -V https://exchange.demo.taler.net/
@end example

@item
The ``master_key'' option specifies the exchange's master public key in base32 encoding.
For the Taler demonstrator, use:

@example
$ taler-config -s merchant-exchange-demo -o master_key \
  -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
@end example

Note that multiple exchanges can be added to the system by using different
tokens in place of @code{demo} in the example above.  Note that all
of the exchanges must use the same currency.  If you need to support
multiple currencies, you need to configure a backend per currency.

@end itemize

@c FIXME: In the future, we need to describe specifying auditors here.
@c @item Auditors

@item Wireformat

In order to receive payments, the merchant backend needs to communicate bank
account details to the exchange.  The banking system used is specified using the
following global option:

@example
[merchant]/wireformat
@end example

The value @code{test} can be used to interact with the Taler
demonstrator at @url{https://bank.demo.taler.net/}:

@example
$ taler-config -s merchant -o wireformat -V test
@end example

Other wireformats will be supported in the future to interact with
actual banks.

@item Instances

The backend allows the user to run multiple instances of shops with
distinct business entities against a single backend.  Each instance
uses its own bank account and key for signing contracts.  It is
mandatory to configure a "default" instance
using the following
options:

@itemize

@item
The option ``keyfile'' in the section ``merchant-instance-default''
specifies the path to the instance's private key.  You do not need to
create a key at this time, the backend will generate it automatically
if it is missing.  While generally unnecessary, it is possible to
generate the key and/or to display the existing public key using the
@code{gnunet-ecc} command-line tool:

@example
$ gnunet-ecc -p                                  \
  `taler-config -f -s merchant-instance-default \
                 -o keyfile`
@end example

@item
The option ``test_response_file'' in the section
``merchant-instance-wireformat-default'' specifies the path to a file
that describes the instance's wire details in JSON format.  The
specific format depends slightly on the banking system selected via
the @code{wireformat} option.

For the @code{test} wire format, a sample specification looks as follows:

@verbatim
{
  "type": "test",
  "bank_uri": "https://bank.test.taler.net/",
  "account_number": 5,
  "salt": "RANDOMSALT"
}
@end verbatim

These bank details are included in the contract in their hashed
form. Hence, the random @code{salt} is necessary to make it difficult
for customers to invert the hash by brute-force.

You should substitute the account number with your actual account
number.  In order to get an account number, register at our
demonstration bank at @url{https://bank.demo.taler.net/} using your
browser.

Assuming this JSON specification is stored in a file @code{$TEST.json},
run:

@example
$ taler-config -s merchant-instance-wireformat-default \
                -o test_response_file -v $TEST.json
@end example


Note that additional instances can be specified using different tokens
in the section name instead of @code{default}.

@end itemize

@end table

@section Sample backend configuration

The following is an example for a complete backend configuration:

@smallexample
[merchant]
wireformat = TEST
serve = TCP
port = 8888
currency = EUR
database = postgres

[merchant-instance-default]
KEYFILE = $DATADIR/key.priv

[merchant-instance-wireformat-default]
TEST_RESPONSE_FILE = $DATADIR/test.json

[merchantdb-postgres]
config = postgres:///donations

[merchant-demoexchange]
uri = https://exchange.demo.taler.net/
master_key = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
@end smallexample



The backend will use a database named @code{donations} within
Postgresql.

The backend will deposit the coins it receives to the exchange at
@url{https://exchange.demo.taler.net/}, which has the master key @*
"CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00".

Please note that @code{doc/config.sh} will walk you through all
configuration steps, showing how to invoke @code{taler-config}
for each of them.

@section Launching the backend

As mentioned previously, the system adminstrator should make sure that
a database named @code{donations} is defined and accessible in the
system. Once this configuration is ready, the
merchant backend can be launched using:

@example
$ taler-merchant-httpd
@end example

If everything worked as expected, the command

@example
$ curl http://localhost:8888/
@end example

should return the message

@smallexample
Hello, I'm a merchant's Taler backend. This HTTP server is not for humans.
@end smallexample

Please note that your backend is right now likely globally
reachable.  Production systems should be configured to bind
to a UNIX domain socket or properly restrict access to the
port.


@node Hello-world
@chapter Setting up a simple Web shop with GNU Taler

This section describes how to setup a simple shop, which exposes a
button to get donations via Taler. The expected behaviour is that once
the ``donate'' button is clicked, the customer will receive a Taler
contract offering him the opportunity to make a fixed donation,
for example to donate 1 KUDOS to the charity operating the shop.

Note that if the customer does not have the Taler wallet installed,
they should instead be prompted to proceed with a classic dialog for
credit card payments.


@section Prompting for payment

Our goal is to trigger a Taler payment once the customer has clicked
on a donation button.  We will use a button that issues an HTTP POST
to the frontend @code{/donate} URL.  For this, the HTML would be as
follows:

@smallexample
<form action="/donate">
  <input type="submit" value="Donate!"></input>
<form>
@end smallexample

When the server-side handler for @code{/donate} receives the form submission,
it will return a HTML page that will take care of:

@itemize
@item showing a credit card paywall to the user if no wallet is found, and
@item fetching a Taler contract and passing it to the wallet if one is found
@end itemize

A minimalistic @code{/donate} handler is shown below (in PHP):

@smallexample
// donate_handler.php
@include examples/donate_handler.php
@end smallexample


Given this response, the Taler wallet will fetch the contract from
@url{/generate-contract} and display it to the user.  If the wallet is not
present, the HTML body will be shown and the Taler headers will be
ignored by the browser.  Instead of specifying the contract via an
URL, it is also possible to inline short contracts directly.

Note that we @emph{could} have bypassed the POST request to trigger
the payment, and performed the interaction with the wallet directly
from the button via JavaScript.

@c We will consider this case in a later chapter.
@c FIXME: not yet ;-)

@section Generating the contract

The server-side handler for @code{/generate-contract} now has to
generate a contract proposal about donating 1 KUDOS to the 'Taler
charity program'.  This proposed contract is then POSTed to the
backend at @code{/contract}.  The main result of POSTing the proposal
to the backend is that it will be cryptographically signed.  This is
necessary as by design the frontend does not perform any cryptographic
work.

A simple @code{/generate-contract} handler may thus look like this:

@smallexample
// generate_contract.php
@include examples/generate_contract.php
@end smallexample

Note that in practice the frontend might want to generate a monotonically
increasing series of transaction IDs to avoid a chance of collisions.
Transaction IDs must be in the range of @math{[0:2^{51})}.

The function @code{post_to_backend} is shown below; we will use it
again in other examples:

@smallexample
// post_to_backend.php
@include examples/post_to_backend.php
@end smallexample

After the browser has fetched the contract, the user will
be given the opportunity to affirm the payment.


@section Receiving payments via Taler

The next step for the frontend is to accept the payment from the wallet,
assuming the user accepts the contract.  For this, the frontend must
implement a payment handler at the URI specified for as the
@code{X-Taler-Pay-Url} in the example above.

The role of the @code{/pay} handler is to receive the payment from
the wallet and forward it to the backend.  If the backend reports
that the payment was successful, the handler needs to update the
session state with the browser to remember that the user paid.
The following code implements this in PHP:

@smallexample
// pay_handler.php
@include examples/pay_handler.php
@end smallexample

Do not be confused by the @code{isset} test for the session state.  In
our simple example, it will be set to ``false'' by the fulfillment URL
which the browser actually always visits first.@footnote{This is for
technical reasons; the natural logical progression would of course be
to pay before accessing the fulfillment URL.}  We describe how the
fulfillment URL works in the next section.


@section The fulfillment page

The fulfillment page can be called by users that have already paid for
the item, as well as by users that have not yet paid at all.  The
fulfillment page must use the HTTP session state to detect if the
payment has been performed already, and if not request payment from
the wallet.

For our example, we include in the URI of the fulfillment page the data
which is needed to allow the page to determine which contract the user is
trying to access.
Thus, the fulfillment URL for our example looks like the following:@*

@smallexample
https://shop.com/fulfillment? \
transaction_id=<TRANSACTION_ID>&timestamp=<CONTRACTTIMESTAMP>
@end smallexample


@*The @code{/fulfillment} handler will then perform the following actions:

@smallexample
// fulfillment_handler.php
@include examples/fulfillment_handler.php
@end smallexample


@node Back-office-integration
@chapter Integration of GNU Taler with the back office


@bye


@node Advanced-topics
@chapter Advanced topics

This chapter includes draft texts for advanced topics which have
not yet been properly integrated with the main text.


@section Using the SEPA wire transfer method

Let's say that all the donations go to the following recipient,
expressed in @code{SEPA} format@footnote{As said, supporting SEPA is still
work in progress}.

@verbatim
{
  "type": "SEPA",
  "IBAN": "XY00 1111 2222 3333 4444 5555 6666",
  "name": "Taler charity program",
  "BIC": "XXXXAB99",
  "salt": "RANDOMSALT"
}

@end verbatim

Assume this information is stored in file @code{$DATADIR/sepa.json}.



@section Payments using JavaScript

The function @code{executePayment} exported by @code{taler-wallet-lib.js} will basically
hand its three parameters to the wallet which implements the following semantics:@*
check in the internal DB if @code{$response['H_contract']} has an entry, and:
@itemize
@item if that is the case, then the user accepted the contract previously and the wallet
sends a deposit permission @footnote{Roughly speaking, a deposit permission is a JSON
containing the coins to pay for a contract. Its full specification is available at:
@url{https://api.taler.net/api-merchant.html#depositpermission}} to @code{/frontend-pay}.
If this operation succeeds, then visit again the fulfillment URL, and finally enjoy
the product.
@item if not, redirect the browser to @code{/donate} (which will then reinitiate the
whole contract negotiation). This happens when the user visits a shared fulfillment URL.
The idea is to let that user buy the same products as the user who shared the fulfillment
URL. Nonetheless, the shop is not forced to follow this semantics when provides the third
parameter to @code{executePayment}.
@end itemize



@section Design considerations for the fulfillment page

The fulfillment page mechanism is designed to provide the following two properties:

@enumerate
@item Taler payments @emph{can} be implemented in DB-less frontends.

@item Taler payments are replayable, meaning that each purchase is associated with
a URL (the fulfillment URL) that shows the product each time it gets visited (and
of course, only the first time takes the user's money).
@end enumerate

In order to implement property (1), the frontend needs a way to recall
what a contract is about (e.g. which product, which price, the
timestamp, etc.) before proceeding with the actual payment and
eventually deliver the final product.  That is achieved by
@emph{reconstructing} the contract using the fulfillment page's URL
parameters@footnote{the fulfillment URL equipped with all the
parameters is included in the contract}.

In order to implement property (2), the frontend will firstly check
the state to see if the product claimed among the fulfillment URL
parameter has been paid; if so, the product is given to the
customer. Otherwise, the frontend sets the payment as "pending" in the
state and @emph{executes} it in the wallet. The payment execution is
performed by returning JavaScript code from @code{taler-wallet-lib.js}
that triggers the wallet to send the payment to the pay page.  Once
the pay page receives the payment, it sets the state for the payment
as "payed".