diff options
Diffstat (limited to 'texinfo')
-rw-r--r-- | texinfo/Makefile | 57 | ||||
-rw-r--r-- | texinfo/onboarding-figures/arch-api.png | bin | 0 -> 59189 bytes | |||
-rw-r--r-- | texinfo/onboarding-figures/exchange-db.png | bin | 0 -> 564934 bytes | |||
-rw-r--r-- | texinfo/onboarding.texi | 663 | ||||
-rw-r--r-- | texinfo/taler-bank-figures/arch-api.png | bin | 0 -> 59189 bytes | |||
-rw-r--r-- | texinfo/taler-bank-figures/exchange-db.png | bin | 0 -> 564934 bytes | |||
-rw-r--r-- | texinfo/taler-bank.texi | 348 | ||||
-rw-r--r-- | texinfo/taler-exchange-figures/exchange-db.png | bin | 0 -> 564934 bytes | |||
-rw-r--r-- | texinfo/taler-exchange.texi | 1122 | ||||
-rw-r--r-- | texinfo/taler-merchant-api-tutorial-figures/arch-api.png | bin | 0 -> 59189 bytes | |||
-rw-r--r-- | texinfo/taler-merchant-api-tutorial-figures/exchange-db.png | bin | 0 -> 564934 bytes | |||
-rw-r--r-- | texinfo/taler-merchant-api-tutorial.texi | 945 | ||||
-rw-r--r-- | texinfo/taler-merchant-figures/exchange-db.png | bin | 0 -> 564934 bytes | |||
-rw-r--r-- | texinfo/taler-merchant.texi | 1461 |
14 files changed, 4596 insertions, 0 deletions
diff --git a/texinfo/Makefile b/texinfo/Makefile new file mode 100644 index 00000000..e3b732cd --- /dev/null +++ b/texinfo/Makefile @@ -0,0 +1,57 @@ +# Makefile for Sphinx Texinfo output + +infodir ?= /usr/share/info + +MAKEINFO = makeinfo --no-split +MAKEINFO_html = makeinfo --no-split --html +MAKEINFO_plaintext = makeinfo --no-split --plaintext +TEXI2PDF = texi2pdf --batch --expand +INSTALL_INFO = install-info + +ALLDOCS = $(basename $(wildcard *.texi)) + +all: info +info: $(addsuffix .info,$(ALLDOCS)) +plaintext: $(addsuffix .txt,$(ALLDOCS)) +html: $(addsuffix .html,$(ALLDOCS)) +pdf: $(addsuffix .pdf,$(ALLDOCS)) + +install-info: info + for f in *.info; do \ + mkdir -p $(infodir) && \ + cp "$$f" $(infodir) && \ + $(INSTALL_INFO) --info-dir=$(infodir) "$$f" && \ + \ + FIGURE_DIR="`basename \"$$f\" .info`-figures" && \ + if [ -e "$$FIGURE_DIR" ]; then \ + cp -r "$$FIGURE_DIR" $(infodir) ; \ + fi; \ + done + +uninstall-info: info + for f in *.info; do \ + rm -f "$(infodir)/$$f" ; \ + rm -rf "$(infodir)/`basename '$$f' .info`-figures" && \ + $(INSTALL_INFO) --delete --info-dir=$(infodir) "$$f" ; \ + done + +%.info: %.texi + $(MAKEINFO) -o '$@' '$<' + +%.txt: %.texi + $(MAKEINFO_plaintext) -o '$@' '$<' + +%.html: %.texi + $(MAKEINFO_html) -o '$@' '$<' + +%.pdf: %.texi + -$(TEXI2PDF) '$<' + -$(TEXI2PDF) '$<' + -$(TEXI2PDF) '$<' + +clean: + rm -f *.info *.pdf *.txt *.html + rm -f *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla *.ky *.pg + rm -f *.vr *.tp *.fn *.fns *.def *.defs *.cp *.cps *.ge *.ges *.mo + +.PHONY: all info plaintext html pdf install-info uninstall-info clean diff --git a/texinfo/onboarding-figures/arch-api.png b/texinfo/onboarding-figures/arch-api.png Binary files differnew file mode 100644 index 00000000..8004f790 --- /dev/null +++ b/texinfo/onboarding-figures/arch-api.png diff --git a/texinfo/onboarding-figures/exchange-db.png b/texinfo/onboarding-figures/exchange-db.png Binary files differnew file mode 100644 index 00000000..421e5941 --- /dev/null +++ b/texinfo/onboarding-figures/exchange-db.png diff --git a/texinfo/onboarding.texi b/texinfo/onboarding.texi new file mode 100644 index 00000000..0ae99b39 --- /dev/null +++ b/texinfo/onboarding.texi @@ -0,0 +1,663 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename onboarding.info +@documentencoding UTF-8 +@ifinfo +@*Generated by Sphinx 2.2.0.@* +@end ifinfo +@settitle Taler Onboarding Manual +@defindex ge +@paragraphindent 0 +@exampleindent 4 +@finalout +@dircategory CATEGORY +@direntry +* MENU ENTRY: (onboarding.info). DESCRIPTION +@end direntry + +@definfoenclose strong,`,' +@definfoenclose emph,`,' +@c %**end of header + +@copying +@quotation +GNU Taler 0.6.0pre1, Sep 18, 2019 + +GNU Taler team + +Copyright @copyright{} 2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+) +@end quotation + +@end copying + +@titlepage +@title Taler Onboarding Manual +@insertcopying +@end titlepage +@contents + +@c %** start of user preamble + +@c %** end of user preamble + +@ifnottex +@node Top +@top Taler Onboarding Manual +@insertcopying +@end ifnottex + +@c %**start of body +@anchor{onboarding doc}@anchor{0} +@menu +* Taler installation:: +* Building the documentation:: +* Building the Websites.: Building the Websites. +* Code coverage.: Code coverage. +* Online services checker.: Online services checker. +* Topping the tip reserve up:: +* Producing auditor reports:: +* Releases:: +* Code:: +* Bugtracking:: +* Continuous integration:: +* Code coverage: Code coverage<2>. +* Appendix:: + +@detailmenu + --- The Detailed Node Listing --- + +Taler installation + +* User Acccounts:: +* Compile and switch color.: Compile and switch color. +* Full bootstrap.: Full bootstrap. +* How to upgrade the code.: How to upgrade the code. + +Releases + +* Release Process and Checklists:: +* Tagging:: +* Database for tests:: +* Exchange@comma{} merchant: Exchange merchant. +* Wallet WebExtension:: +* Upload to GNU mirrors:: + +Appendix + +* Testing library:: + +@end detailmenu +@end menu + +@node Taler installation,Building the documentation,Top,Top +@anchor{onboarding developer-onboarding-manual}@anchor{1}@anchor{onboarding taler-installation}@anchor{2} +@chapter Taler installation + + +This section describes the GNU Taler deployment on @code{gv.taler.net}. + +@menu +* User Acccounts:: +* Compile and switch color.: Compile and switch color. +* Full bootstrap.: Full bootstrap. +* How to upgrade the code.: How to upgrade the code. + +@end menu + +@node User Acccounts,Compile and switch color,,Taler installation +@anchor{onboarding user-acccounts}@anchor{3} +@section User Acccounts + + +On @code{gv.taler.net}, there are four users that are set up to serve Taler on +the internet: + + +@itemize - + +@item +@code{taler-test}: serves @code{*.test.taler.net} and gets automatically +built by Buildbot. + +@item +@code{taler-internal}: serves @code{*.int.taler.net}, and does @emph{NOT} get +automatically built. +@end itemize + +The following two users are @emph{never} automatically built, and they both +serve @code{*.demo.taler.net}. At any given time, only one is active and +serves the HTTP requests from the outside; the other one can so be +compiled without any downtime. If the compilation succeeds, the inactive +user can be switched to become active (see next section), and vice versa. + + +@itemize - + +@item +@code{demo-blue} + +@item +@code{demo-green} +@end itemize + +@node Compile and switch color,Full bootstrap,User Acccounts,Taler installation +@anchor{onboarding compile-and-switch-color}@anchor{4} +@section Compile and switch color. + + +If the setup is already bootstrapped, then it should only be needed to +login as ’demo-X’ (with X being the inactive color); and then: + +@example +$ source activate +$ taler-deployment-build +@end example + +and then switch the color by logging in as the @emph{demo} user, and switch +the color with the following command: + +@example +$ taler-deployment-switch-demo-X +@end example + +@node Full bootstrap,How to upgrade the code,Compile and switch color,Taler installation +@anchor{onboarding full-bootstrap}@anchor{5} +@section Full bootstrap. + + +In order to bootstrap a Taler installation under a empty home directory, +do: + +@example +$ cd $HOME +$ git clone git://git.taler.net/deployment +@end example + +Then run the prepare script that will (1) download all the repositories +(2) build the codebases, (3) configure the system, and (4) generate the +needed data. + + +@table @asis + +@item :: + +$ ./deployment/bin/taler-deployment-prepare [test | int | demo] +@end table + + +@quotation + +@strong{Note} + +If the DB schema of merchant/exchange/auditor changed, at this point +it MIGHT be necessary to reset all the tables. To this regard, +consider running one of the following commands: + +@example +# To reset the merchant DB. +$ taler-merchant-dbinit -r + +# To reset the exchange DB. +$ taler-exchange-dbinit -r + +# To reset the exchange DB. +$ taler-auditor-dbinit -r +@end example +@end quotation + +If all the steps succeeded, then it should be possible to launch all the +services. Give: + +@example +$ taler-deployment-start + +# or restart, if you want to kill old processes and +# start new ones. +$ taler-deployment-restart +@end example + +Verify that all services are up and running: + +@example +$ taler-deployment-arm -I +$ tail logs/<component>-<date>.log +@end example + +@node How to upgrade the code,,Full bootstrap,Taler installation +@anchor{onboarding how-to-upgrade-the-code}@anchor{6} +@section How to upgrade the code. + + +Some repositories, especially the ones from the released components, +have a @emph{stable} branch, that keeps older and more stable code. +Therefore, upon each release we must rebase those stable branches on the +master. + +The following commands do that: + +@example +$ cd $REPO + +$ git pull origin master stable +$ git checkout stable + +# option a: resolve conflicts resulting from hotfixes +$ git rebase master +$ ... + +# option b: force stable to master +$ git update-ref refs/heads/stable master + +$ git push # possibly with --force + +# continue development +$ git checkout master +@end example + +@node Building the documentation,Building the Websites,Taler installation,Top +@anchor{onboarding building-the-documentation}@anchor{7}@anchor{onboarding testing-components}@anchor{8} +@chapter Building the documentation + + +All the Taler documentation is built by the user @cite{docbuilder} that +runs a Buildbot worker. The following commands set the @cite{docbuilder} up, +starting with a empty home directory. + + +@table @asis + +@item :: + +# Log-in as the 'docbuilder' user. + +$ cd $HOME +$ git clone git://git.taler.net/deployment +$ ./deployment/bootstrap-docbuilder + +# If the previous step worked, the setup is +# complete and the Buildbot worker can be started. + +$ buildbot-worker start worker/ +@end table + +@node Building the Websites,Code coverage,Building the documentation,Top +@anchor{onboarding building-the-websites}@anchor{9} +@chapter Building the Websites. + + +Taler Websites, @cite{www.taler.net} and @cite{stage.taler.net}, are built by the +user @cite{taler-websites} by the means of a Buildbot worker. The following +commands set the @cite{taler-websites} up, starting with a empty home directory. + + +@table @asis + +@item :: + +# Log-in as the 'taler-websites' user. + +$ cd $HOME +$ git clone git://git.taler.net/deployment +$ ./deployment/bootstrap-sitesbuilder + +# If the previous step worked, the setup is +# complete and the Buildbot worker can be started. + +$ buildbot-worker start worker/ +@end table + +@node Code coverage,Online services checker,Building the Websites,Top +@anchor{onboarding code-coverage}@anchor{a} +@chapter Code coverage. + + +Code coverage tests are run by the @cite{lcovworker} user, and are also driven +by Buildbot. + +@example +# Log-in as the 'lcovworker' user. + +$ cd $HOME +$ git clone git://git.taler.net/deployment +$ ./deployment/bootstrap-taler lcov + +# If the previous step worked, the setup is +# complete and the Buildbot worker can be started. + +$ buildbot-worker start worker/ +@end example + +The results are then published at @cite{https://lcov.taler.net/}. + +@node Online services checker,Topping the tip reserve up,Code coverage,Top +@anchor{onboarding online-services-checker}@anchor{b} +@chapter Online services checker. + + +The user @cite{demo-checker} runs periodic checks to see if all the +@cite{*.demo.taler.net} services are up and running. It is driven by +Buildbot, and can be bootstrapped as follows. + +@example +# Log-in as the 'demo-checker' user + +$ cd $HOME +$ git clone git://git.taler.net/deployment +$ ./deployment/bootstrap-demochecker + +# If the previous step worked, the setup is +# complete and the Buildbot worker can be started. + +$ buildbot-worker start worker/ +@end example + +@node Topping the tip reserve up,Producing auditor reports,Online services checker,Top +@anchor{onboarding topping-the-tip-reserve-up}@anchor{c} +@chapter Topping the tip reserve up + + +Both 'test' and 'demo' setups get their tip reserve topped up +by a Buildbot worker. The following steps get the reserve topper +prepared. + + +@table @asis + +@item :: + +# Log-in as <env>-topper, with <env> being either 'test' or 'demo' + +$ git clone git://git.taler.net/deployment +$ ./deployment/prepare-reservetopper <env> + +# If the previous steps worked, then it should suffice to start +# the worker, with: + +$ buildbot-worker start worker/ +@end table + +@node Producing auditor reports,Releases,Topping the tip reserve up,Top +@anchor{onboarding producing-auditor-reports}@anchor{d} +@chapter Producing auditor reports + + +Both 'test' and 'demo' setups get their auditor reports compiled +by a Buildbot worker. The following steps get the reports compiler +prepared. + + +@table @asis + +@item :: + +# Log-in as <env>-auditor, with <env> being either 'test' or 'demo' + +$ git clone git://git.taler.net/deployment +$ ./deployment/prepare-auditorreporter <env> + +# If the previous steps worked, then it should suffice to start +# the worker, with: + +$ buildbot-worker start worker/ +@end table + +@node Releases,Code,Producing auditor reports,Top +@anchor{onboarding id1}@anchor{e}@anchor{onboarding releases}@anchor{f} +@chapter Releases + + +@menu +* Release Process and Checklists:: +* Tagging:: +* Database for tests:: +* Exchange@comma{} merchant: Exchange merchant. +* Wallet WebExtension:: +* Upload to GNU mirrors:: + +@end menu + +@node Release Process and Checklists,Tagging,,Releases +@anchor{onboarding release-process-and-checklists}@anchor{10} +@section Release Process and Checklists + + +This document describes the process for releasing a new version of the +various Taler components to the official GNU mirrors. + +The following components are published on the GNU mirrors + + +@itemize - + +@item +taler-exchange (exchange.git) + +@item +taler-merchant (merchant.git) + +@item +talerdonations (donations.git) + +@item +talerblog (blog.git) + +@item +taler-bank (bank.git) + +@item +taler-wallet-webex (wallet-webex.git) +@end itemize + +@node Tagging,Database for tests,Release Process and Checklists,Releases +@anchor{onboarding tagging}@anchor{11} +@section Tagging + + +Tag releases with an @strong{annotated} commit, like + +@example +git tag -a v0.1.0 -m "Official release v0.1.0" +git push origin v0.1.0 +@end example + +@node Database for tests,Exchange merchant,Tagging,Releases +@anchor{onboarding database-for-tests}@anchor{12} +@section Database for tests + + +For tests in the exchange and merchant to run, make sure that a database +@emph{talercheck} is accessible by @emph{$USER}. Otherwise tests involving the +database logic are skipped. + +@node Exchange merchant,Wallet WebExtension,Database for tests,Releases +@anchor{onboarding exchange-merchant}@anchor{13} +@section Exchange, merchant + + +Set the version in @code{configure.ac}. The commit being tagged should be +the change of the version. + +For the exchange test cases to pass, @code{make install} must be run first. +Without it, test cases will fail because plugins can’t be located. + +@example +./bootstrap +./configure # add required options for your system +make dist +tar -xf taler-$COMPONENT-$VERSION.tar.gz +cd taler-$COMPONENT-$VERSION +make install check +@end example + +@node Wallet WebExtension,Upload to GNU mirrors,Exchange merchant,Releases +@anchor{onboarding wallet-webextension}@anchor{14} +@section Wallet WebExtension + + +The version of the wallet is in @emph{manifest.json}. The @code{version_name} +should be adjusted, and @emph{version} should be increased independently on +every upload to the WebStore. + +@example +./configure +make dist +@end example + +@node Upload to GNU mirrors,,Wallet WebExtension,Releases +@anchor{onboarding upload-to-gnu-mirrors}@anchor{15} +@section Upload to GNU mirrors + + +See +@emph{https://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads} + +Directive file: + +@example +version: 1.2 +directory: taler +filename: taler-exchange-0.1.0.tar.gz +@end example + +Upload the files in @strong{binary mode} to the ftp servers. + +@node Code,Bugtracking,Releases,Top +@anchor{onboarding code}@anchor{16}@anchor{onboarding id2}@anchor{17} +@chapter Code + + +Taler code is versioned via Git. For those users without write access, +all the codebases are found at the following URL: + +@example +git://git.taler.net/<repository> +@end example + +A complete list of all the existing repositories is currently found at +@code{https://git.taler.net/}. Note: @code{<repository>} must NOT have the +@code{.git} extension. + +@node Bugtracking,Continuous integration,Code,Top +@anchor{onboarding bugtracking}@anchor{18}@anchor{onboarding id3}@anchor{19} +@chapter Bugtracking + + +Bug tracking is done with Mantis (@indicateurl{https://www.mantisbt.org/}). All the +bugs are then showed and managed at @code{https://bugs.gnunet.org/}, under +the "Taler" project. A registration on the Web site is needed in order +to use the bug tracker. + +@node Continuous integration,Code coverage<2>,Bugtracking,Top +@anchor{onboarding continuous-integration}@anchor{1a}@anchor{onboarding id4}@anchor{1b} +@chapter Continuous integration + + +CI is done with Buildbot (@indicateurl{https://buildbot.net/}), and builds are +triggered by the means of Git hooks. The results are published at +@code{https://buildbot.wild.gv.taler.net/}. + +In order to avoid downtimes, CI uses a "blue/green" deployment +technique. In detail, there are two users building code on the system, +the "green" and the "blue" user; and at any given time, one is running +Taler services and the other one is either building the code or waiting +for that. + +There is also the possibility to trigger builds manually, but this is +only reserved to "admin" users. + +@node Code coverage<2>,Appendix,Continuous integration,Top +@anchor{onboarding id5}@anchor{1c}@anchor{onboarding id6}@anchor{1d} +@chapter Code coverage + + +Code coverage is done with the Gcov / Lcov +(@indicateurl{http://ltp.sourceforge.net/coverage/lcov.php}) combo, and it is run +*nightly* (once a day) by a Buildbot worker. The coverage results are +then published at @code{https://lcov.taler.net/}. + +@node Appendix,,Code coverage<2>,Top +@anchor{onboarding appendix}@anchor{1e} +@chapter Appendix + + +@menu +* Testing library:: + +@end menu + +@node Testing library,,,Appendix +@anchor{onboarding testing-library}@anchor{1f} +@section Testing library + + +This chapter is a VERY ABSTRACT description of how testing is +implemented in Taler, and in NO WAY wants to substitute the reading of +the actual source code by the user. + +In Taler, a test case is a array of @code{struct TALER_TESTING_Command}, +informally referred to as @code{CMD}, that is iteratively executed by the +testing interpreter. This latter is transparently initiated by the +testing library. + +However, the developer does not have to defined CMDs manually, but +rather call the proper constructor provided by the library. For example, +if a CMD is supposed to test feature @code{x}, then the library would +provide the @code{TALER_TESTING_cmd_x ()} constructor for it. Obviously, +each constructor has its own particular arguments that make sense to +test @code{x}, and all constructor are thoroughly commented within the +source code. + +Internally, each CMD has two methods: @code{run ()} and @code{cleanup ()}. The +former contains the main logic to test feature @code{x}, whereas the latter +cleans the memory up after execution. + +In a test life, each CMD needs some internal state, made by values it +keeps in memory. Often, the test has to @emph{share} those values with other +CMDs: for example, CMD1 may create some key material and CMD2 needs this +key material to encrypt data. + +The offering of internal values from CMD1 to CMD2 is made by @emph{traits}. A +trait is a @code{struct TALER_TESTING_Trait}, and each CMD contains a array +of traits, that it offers via the public trait interface to other +commands. The definition and filling of such array happens transparently +to the test developer. + +For example, the following example shows how CMD2 takes an amount object +offered by CMD1 via the trait interface. + +Note: the main interpreter and the most part of CMDs and traits are +hosted inside the exchange codebase, but nothing prevents the developer +from implementing new CMDs and traits within other codebases. + +@example +/* Withouth loss of generality, let's consider the + * following logic to exist inside the run() method of CMD1 */ +.. + +struct TALER_Amount *a; +/** + * the second argument (0) points to the first amount object offered, + * in case multiple are available. + */ +if (GNUNET_OK != TALER_TESTING_get_trait_amount_obj (cmd2, 0, &a)) + return GNUNET_SYSERR; +... + +use(a); /* 'a' points straight into the internal state of CMD2 */ +@end example + +In the Taler realm, there is also the possibility to alter the behaviour +of supposedly well-behaved components. This is needed when, for example, +we want the exchange to return some corrupted signature in order to +check if the merchant backend detects it. + +This alteration is accomplished by another service called @emph{twister}. The +twister acts as a proxy between service A and B, and can be programmed +to tamper with the data exchanged by A and B. + +Please refer to the Twister codebase (under the @code{test} directory) in +order to see how to configure it. + +@c %**end of body +@bye diff --git a/texinfo/taler-bank-figures/arch-api.png b/texinfo/taler-bank-figures/arch-api.png Binary files differnew file mode 100644 index 00000000..8004f790 --- /dev/null +++ b/texinfo/taler-bank-figures/arch-api.png diff --git a/texinfo/taler-bank-figures/exchange-db.png b/texinfo/taler-bank-figures/exchange-db.png Binary files differnew file mode 100644 index 00000000..421e5941 --- /dev/null +++ b/texinfo/taler-bank-figures/exchange-db.png diff --git a/texinfo/taler-bank.texi b/texinfo/taler-bank.texi new file mode 100644 index 00000000..78293b57 --- /dev/null +++ b/texinfo/taler-bank.texi @@ -0,0 +1,348 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename taler-bank.info +@documentencoding UTF-8 +@ifinfo +@*Generated by Sphinx 2.2.0.@* +@end ifinfo +@settitle Taler Bank Manual +@defindex ge +@paragraphindent 0 +@exampleindent 4 +@finalout +@dircategory CATEGORY +@direntry +* MENU ENTRY: (taler-bank.info). DESCRIPTION +@end direntry + +@definfoenclose strong,`,' +@definfoenclose emph,`,' +@c %**end of header + +@copying +@quotation +GNU Taler 0.6.0pre1, Sep 18, 2019 + +GNU Taler team + +Copyright @copyright{} 2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+) +@end quotation + +@end copying + +@titlepage +@title Taler Bank Manual +@insertcopying +@end titlepage +@contents + +@c %** start of user preamble + +@c %** end of user preamble + +@ifnottex +@node Top +@top Taler Bank Manual +@insertcopying +@end ifnottex + +@c %**start of body +@anchor{taler-bank-manual doc}@anchor{0} +@menu +* Introduction:: +* Reference:: + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* About GNU Taler:: +* About this manual:: + +Reference + +* Bank-Wallet interaction:: +* Bank-Exchange interaction:: + +Bank-Exchange interaction + +* Withdraw:: +* Exchange pays merchant:: + +@end detailmenu +@end menu + +@node Introduction,Reference,Top,Top +@anchor{taler-bank-manual gnu-taler-bank-manual}@anchor{1}@anchor{taler-bank-manual introduction}@anchor{2} +@chapter Introduction + + +@menu +* About GNU Taler:: +* About this manual:: + +@end menu + +@node About GNU Taler,About this manual,,Introduction +@anchor{taler-bank-manual about-gnu-taler}@anchor{3} +@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). + +@node About this manual,,About GNU Taler,Introduction +@anchor{taler-bank-manual about-this-manual}@anchor{4} +@section About this manual + + +This manual documents how the demonstrator bank interoperates with the +other GNU Taler components. The demonstrator bank implements a simple +closed banking system for the purpose of illustrating how GNU Taler +works in the Taler demo. It could also be used as a starting point for a +local/regional currency. Finally, “real” banks might use it as a +reference implementation for a tight integration with the GNU Taler +wallet. + +@node Reference,,Introduction,Top +@anchor{taler-bank-manual id1}@anchor{5}@anchor{taler-bank-manual reference}@anchor{6} +@chapter Reference + + +@menu +* Bank-Wallet interaction:: +* Bank-Exchange interaction:: + +@end menu + +@node Bank-Wallet interaction,Bank-Exchange interaction,,Reference +@anchor{taler-bank-manual bank-002dwallet-interaction}@anchor{7}@anchor{taler-bank-manual bank-wallet-interaction}@anchor{8} +@section Bank-Wallet interaction + + +The HTTP status code @code{202 Accepted} can be used by the bank website to +trigger operations in the user agent. The operation is determined by the +@code{X-Taler-Operation} header. The following operations are understood: + + +@table @asis + +@item @code{create-reserve} + +Ask the Taler wallet to create a reserve and call back the bank with +the reserve public key. The following headers are mandatory: + + +@itemize - + +@item +@code{X-Taler-Callback-Url}: URL that the wallet will visit when the +reserve was created and the user has selected an exchange. + +@item +@code{X-Taler-Wt-Types}: JSON-encoded array of wire transfer types +that this bank supports. + +@item +@code{X-Taler-Amount}: The amount that will be transferred to the +reserve. + +@item +@code{X-Taler-Sender-Wire}: JSON-encoded wire account details of the +sender, that is the user that is currently logged in with the bank +and creates the reserve. +@end itemize + +The following header is optional: + + +@itemize - + +@item +@code{X-Taler-Suggested-Exchange}: Exchange that the bank recommends +the customer to use. Note that this is a suggestion and can be +ignored by the wallet or changed by the user. +@end itemize + +On successful reserve creation, the wallet will navigate to the +callback URL (effectively requesting it with a GET) with the +following additional request parameters: + + +@itemize - + +@item +@code{exchange}: The URL of the exchange selected by the user + +@item +@code{wire_details}: The wire details of the exchange. + +@item +@code{reserve_pub}: The reserve public key that the bank should +transmit to the exchange when transmitting the funds. +@end itemize + +@item @code{confirm-reserve} + +To secure the operation, the (demo) bank then shows a "CAPTCHA page" +– a real bank would instead show some PIN entry dialog or similar +security method – where the customer can finally prove she their +identity and thereby confirm the withdraw operation to the bank. + +Afterwards, the bank needs to confirm to the wallet that the user +completed the required steps to transfer funds to an exchange to +establish the reserve identified by the @code{X-Taler-Reserve-Pub} +header. + +This does not guarantee that the reserve is already created at the +exchange (since the actual money transfer might be executed +asynchronously), but it informs that wallet that it can start polling +for the reserve. +@end table + +@node Bank-Exchange interaction,,Bank-Wallet interaction,Reference +@anchor{taler-bank-manual bank-002dexchange-interaction}@anchor{9}@anchor{taler-bank-manual bank-exchange-interaction}@anchor{a} +@section Bank-Exchange interaction + + +The interaction between a bank and the exchange happens in two +situations: when a wallet withdraws coins, and when the exchange pays a +merchant. + +@menu +* Withdraw:: +* Exchange pays merchant:: + +@end menu + +@node Withdraw,Exchange pays merchant,,Bank-Exchange interaction +@anchor{taler-bank-manual withdraw}@anchor{b} +@subsection Withdraw + + +Once a withdrawal operation with the wallet has been confirmed, the the +bank must wire transfer the withdrawn amount from the customer account +to the exchange’s. After this operation is done, the exchange needs to +be informed so that it will create the reserve. + +For the moment, the bank will use the exchange’s @code{/admin/add/incoming} +API, providing those arguments it got along the @code{X-Taler-Callback-Url} +URL. (In the future, the exchange will poll for this information.) +However, the bank will define two additional values for this API: +@code{execution_date} (a operation’s timestamp), and @code{transfer_details} +(just a "seed" to make unique the operation). See +@indicateurl{https://docs.taler.net/api/api-exchange.html#administrative-api-bank-transactions}. + +The polling mechanism is possbile thanks to the @code{/history} API +provided by the bank. The exchange will periodically use this API to see +if it has received new wire transfers; upon receiving a new wire +transfer, the exchange will automatically create a reserve and allow the +money sender to withdraw. + + +@table @asis + +@item @code{GET /history} + +Ask the bank to return a list of money transactions related to a +caller’s bank account. + + +@itemize - + +@item +@code{auth} a string indicating the authentication method to use; +only @code{"basic"} value is accepted so far. The username and +password credentials have to be sent along the HTTP request +headers. Namely, the bank will look for the following two headers: +@code{X-Taler-Bank-Username} and @code{X-Taler-Bank-Password}, which +will contain those plain text credentials. + +@item +@code{delta} returns the first @code{N} records younger (older) than +@code{start} if @code{+N} (@code{-N}) is specified. + +@item +@code{start} according to delta, only those records with row id +strictly greater (lesser) than start will be returned. This +argument is optional; if not given, delta youngest records will be +returned. + +@item +@code{direction} optional argument taking values debit or credit, +according to the caller willing to receive both incoming and +outgoing, only outgoing, or only incoming records + +@item +@code{account_number} optional argument indicating the bank account +number whose history is to be returned. If not given, then the +history of the calling user will be returned +@end itemize +@end table + +@node Exchange pays merchant,,Withdraw,Bank-Exchange interaction +@anchor{taler-bank-manual exchange-pays-merchant}@anchor{c} +@subsection Exchange pays merchant + + +To allow the exchange to send payments to a merchant, the bank exposes +the @code{/admin/add/incoming} API to exchanges. + + +@table @asis + +@item @code{POST /admin/add/incoming} + +Ask the bank to transfer money from the caller’s account to the +receiver’s. + + +@itemize - + +@item +@code{auth} a string indicating the authentication method to use; +only @code{"basic"} value is accepted so far. The username and +password credentials have to be sent along the HTTP request +headers. Namely, the bank will look for the following two headers: +@code{X-Taler-Bank-Username} and @code{X-Taler-Bank-Password}, which +will contain those plain text credentials. + +@item +@code{amount} a JSON object complying to the Taler amounts layout. +Namely, this object must contain the following fields: @code{value} +(number), @code{fraction} (number), and @code{currency} (string). + +@item +@code{exchange_url} a string indicating the calling exchange base +URL. The bank will use this value to define wire transfers subject +lines. + +@item +@code{wtid} a alphanumeric string that uniquely identifies this +transfer at the exchange database. The bank will use this value +too to define wire transfers subject lines. Namely, subject lines +will have the following format: @code{'wtid exchange_url'}. + +@item +@code{debit_account} number indicating the exchange bank account. +NOTE: this field is currently ignored, as the bank can retrieve +the exchange account number from the login credentials. However, +in future release, an exchange could have multiple account at the +same bank, thereby it will have the chance to specify any of them +in this field. + +@item +@code{credit_account} bank account number that will receive the +transfer. Tipically the merchant account number. +@end itemize +@end table + +@c %**end of body +@bye diff --git a/texinfo/taler-exchange-figures/exchange-db.png b/texinfo/taler-exchange-figures/exchange-db.png Binary files differnew file mode 100644 index 00000000..421e5941 --- /dev/null +++ b/texinfo/taler-exchange-figures/exchange-db.png diff --git a/texinfo/taler-exchange.texi b/texinfo/taler-exchange.texi new file mode 100644 index 00000000..e6c95a4a --- /dev/null +++ b/texinfo/taler-exchange.texi @@ -0,0 +1,1122 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename taler-exchange.info +@documentencoding UTF-8 +@ifinfo +@*Generated by Sphinx 2.2.0.@* +@end ifinfo +@settitle Taler Exchange Manual +@defindex ge +@paragraphindent 0 +@exampleindent 4 +@finalout +@dircategory CATEGORY +@direntry +* MENU ENTRY: (taler-exchange.info). DESCRIPTION +@end direntry + +@definfoenclose strong,`,' +@definfoenclose emph,`,' +@c %**end of header + +@copying +@quotation +GNU Taler 0.6.0pre1, Sep 18, 2019 + +GNU Taler team + +Copyright @copyright{} 2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+) +@end quotation + +@end copying + +@titlepage +@title Taler Exchange Manual +@insertcopying +@end titlepage +@contents + +@c %** start of user preamble + +@c %** end of user preamble + +@ifnottex +@node Top +@top Taler Exchange Manual +@insertcopying +@end ifnottex + +@c %**start of body +@anchor{taler-exchange-manual doc}@anchor{0} +@menu +* Introduction:: +* Installation:: +* Configuration:: +* Deployment:: +* Diagnostics:: + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* About GNU Taler:: +* About this manual:: +* Organizational prerequisites:: +* Architecture overview:: + +Configuration + +* Configuration format:: +* Using taler-config:: +* Keying:: +* Serving:: +* Currency:: +* Bank account:: +* Database:: +* Coins (denomination keys): Coins denomination keys. +* Keys duration:: + +Bank account + +* Wire plugin “taler_bank”:: +* Wire plugin “ebics”:: +* Wire fee structure:: + +Deployment + +* Keys generation:: +* Database upgrades:: + +Diagnostics + +* Reserve management:: +* Database Scheme:: +* Signing key storage:: +* Denomination key storage:: +* Auditor signature storage:: + +Denomination key storage + +* Revocations:: + +@end detailmenu +@end menu + +@node Introduction,Installation,Top,Top +@anchor{taler-exchange-manual gnu-taler-exchange-operator-manual}@anchor{1}@anchor{taler-exchange-manual introduction}@anchor{2} +@chapter Introduction + + +This manual is an early draft that still needs significant editing work +to become readable. + +@menu +* About GNU Taler:: +* About this manual:: +* Organizational prerequisites:: +* Architecture overview:: + +@end menu + +@node About GNU Taler,About this manual,,Introduction +@anchor{taler-exchange-manual about-gnu-taler}@anchor{3} +@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). + +GNU Taler is not yet production-ready, after following this manual you +will have a backend that can process payments in “KUDOS”, but not +regular currencies. This is not so much because of limitations in the +backend, but because we are not aware of a Taler exchange operator +offering regular currencies today. + +@node About this manual,Organizational prerequisites,About GNU Taler,Introduction +@anchor{taler-exchange-manual about-this-manual}@anchor{4} +@section About this manual + + +This tutorial targets system administrators who want to install and +operate a GNU Taler exchange. + +@node Organizational prerequisites,Architecture overview,About this manual,Introduction +@anchor{taler-exchange-manual organizational-prerequisites}@anchor{5} +@section Organizational prerequisites + + +Operating a GNU Taler exchange means that you are operating a payment +service provider, which means that you will most likely need a bank +license and/or follow applicable financial regulation. + +GNU Taler payment service providers generally need to ensure high +availability and have @emph{really} good backups (synchronous replication, +asynchronous remote replication, off-site backup, 24/7 monitoring, +etc.). @footnote{@w{(1)} +Naturally, you could operate a Taler exchange for a toy currency +without any real value on low-cost setups like a Raspberry Pi, but we +urge you to limit the use of such setups to research and education as +with GNU Taler data loss instantly results in financial losses. +} This manual will not cover these aspects of operating a +payment service provider. + +We will assume that you can operate a (high-availability, +high-assurance) Postgres database. Furthermore, we expect some moderate +familiarity with the compilation and installation of free software +packages. You need to understand the cryptographic concepts of private +and public keys and must be able to protect private keys stored in files +on disk. An exchange uses an @emph{offline} master key as well as @emph{online} +keys. You are advised to secure your private master key and any copies +on encrypted, always-offline computers. Again, we assume that you are +familiar with good best practices in operational security, including +securing key material. @footnote{@w{(2)} +The current implementation does not make provisions for secret +splitting. Still, the use of a hardware security module (HSM) for +protecting private keys is adviseable, so please contact the +developers for HSM integration support. +} + +@node Architecture overview,,Organizational prerequisites,Introduction +@anchor{taler-exchange-manual architecture-overview}@anchor{6} +@section Architecture overview + + +Taler is a pure payment system, not a new crypto-currency. As such, it +operates in a traditional banking context. In particular, this means +that in order to receive funds via Taler, the merchant must have a +regular bank account, and payments can be executed in ordinary +currencies such as USD or EUR. Similarly, the Taler exchange must +interact with a bank. The bank of the exchange holds the exchange’s +funds in an escrow account. + +When customers wire money to the escrow account, the bank notifies the +exchange about the incoming wire transfers. The exchange then creates a +@emph{reserve} based on the subject of the wire transfer. The wallet which +knows the secret key matching the wire transfer subject can then +withdraw coins from the reserve, thereby draining it. The liability of +the exchange against the reserve is thereby converted into a liability +against digital coins issued by the exchange. When the customer later +spends the coins at a merchant, and the merchant @emph{deposits} the coins at +the exchange, the exchange first @emph{aggregates} the amount from multiple +deposits from the same merchant and then instructs its bank to make a +wire transfer to the merchant, thereby fulfilling its obligation and +eliminating the liability. The exchange charges @emph{fees} for some or all +of its operations to cover costs and possibly make a profit. + +@emph{Auditors} are third parties, for example financial regulators, that +verify that the exchange operates correctly. The same software is also +used to calculate the exchange’s profits, risk and liabilities by the +accountants of the exchange. + +The Taler software stack for an exchange consists of the following +components: + + +@itemize - + +@item +HTTP frontend +The HTTP frontend interacts with Taler wallets and merchant backends. +It is used to withdraw coins, deposit coins, refresh coins, issue +refunds, map wire transfers to Taler transactions, inquire about the +exchange’s bank account details, signing keys and fee structure. The +binary is the @code{taler-exchange-httpd}. + +@item +Aggregator +The aggregator combines multiple deposits made by the same merchant +and (eventually) triggers wire transfers for the aggregate amount. +The merchant can control how quickly wire transfers are made. The +exchange may be charge a fee per wire transfer to discourage +excessively frequent transfers. The binary is the +@code{taler-exchange-aggregator}. + +@item +Auditor +The auditor verifies that the transactions performed by the exchange +were done properly. It checks the various signatures, totals up the +amounts and alerts the operator to any inconsistencies. It also +computes the expected bank balance, revenue and risk exposure of the +exchange operator. The main binary is the @code{taler-auditor}. + +@item +Wire plugin +A wire plugin enables the HTTP frontend to talk to the bank. Its role +is to allow the exchange to validate bank addresses (i.e. IBAN +numbers), for the aggregator to execute wire transfers and for the +auditor to query bank transaction histories. Wire plugins are +@emph{plugins} as there can be many different implementations to deal with +different banking standards. Wire plugins are automatically located +and used by the exchange, aggregator and auditor. + +@item +DBMS +Postgres +The exchange requires a DBMS to stores the transaction history for +the Taler exchange and aggregator, and a (typically separate) DBMS +for the Taler auditor. For now, the GNU Taler reference implemenation +only supports Postgres, but the code could be easily extended to +support another DBMS. +@end itemize + +@node Installation,Configuration,Introduction,Top +@anchor{taler-exchange-manual installation}@anchor{7} +@chapter Installation + + +Please install the following packages before proceeding with the +exchange compilation. + + +@itemize - + +@item +GNU autoconf >= 2.69 + +@item +GNU automake >= 1.14 + +@item +GNU libtool >= 2.4 + +@item +GNU autopoint >= 0.19 + +@item +GNU libltdl >= 2.4 + +@item +GNU libunistring >= 0.9.3 + +@item +libcurl >= 7.26 (or libgnurl >= 7.26) + +@item +GNU libmicrohttpd >= 0.9.59 + +@item +GNU libgcrypt >= 1.6 + +@item +libjansson >= 2.7 + +@item +Postgres >= 9.6, including libpq + +@item +libgnunetutil (from Git) + +@item +GNU Taler exchange (from Git) +@end itemize + +Except for the last two, these are available in most GNU/Linux +distributions and should just be installed using the respective package +manager. + +The following instructions will show how to install libgnunetutil and +the GNU Taler exchange. + +Before you install libgnunetutil, you must download and install the +dependencies mentioned above, otherwise the build may succeed but fail +to export some of the tooling required by Taler. + +To download and install libgnunetutil, proceed as follows: + +@example +$ git clone https://git.gnunet.org/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}. + +To download and install the GNU Taler exchange, proceeds as follows: + +@example +$ git clone git://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. + +@node Configuration,Deployment,Installation,Top +@anchor{taler-exchange-manual configuration}@anchor{8} +@chapter Configuration + + +This chapter provides an overview of the exchange configuration. Or at +least eventually will do so, for now it is a somewhat wild description +of some of the options. + +@menu +* Configuration format:: +* Using taler-config:: +* Keying:: +* Serving:: +* Currency:: +* Bank account:: +* Database:: +* Coins (denomination keys): Coins denomination keys. +* Keys duration:: + +@end menu + +@node Configuration format,Using taler-config,,Configuration +@anchor{taler-exchange-manual configuration-format}@anchor{9} +@section Configuration format + + +configuration +In Taler realm, any component obeys to the same pattern to get +configuration values. According to this pattern, once the component has +been installed, the installation deploys default values in +$@{prefix@}/share/taler/config.d/, in .conf files. In order to override +these defaults, the user can write a custom .conf file and either pass +it to the component at execution time, or name it taler.conf and place +it under $HOME/.config/. + +A config file is a text file containing sections, and each section +contains its values. The right format follows: + +@example +[section1] +value1 = string +value2 = 23 + +[section2] +value21 = string +value22 = /path22 +@end example + +Throughout any configuration file, it is possible to use @code{$}-prefixed +variables, like @code{$VAR}, especially when they represent filesystem +paths. It is also possible to provide defaults values for those +variables that are unset, by using the following syntax: +@code{$@{VAR:-default@}}. However, there are two ways a user can set +@code{$}-prefixable variables: + +by defining them under a @code{[paths]} section, see example below, + +@example +[paths] +TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data +.. +[section-x] +path-x = $@{TALER_DEPLOYMENT_SHARED@}/x +@end example + +or by setting them in the environment: + +@example +$ export VAR=/x +@end example + +The configuration loader will give precedence to variables set under +@code{[path]}, though. + +The utility @code{taler-config}, which gets installed along with the +exchange, serves to get and set configuration values without directly +editing the .conf. The option @code{-f} is particularly useful to resolve +pathnames, when they use several levels of @code{$}-expanded variables. See +@code{taler-config --help}. + +Note that, in this stage of development, the file +@code{$HOME/.config/taler.conf} can contain sections for @emph{all} the +component. For example, both an exchange and a bank can read values from +it. + +The repository @code{git://taler.net/deployment} contains examples of +configuration file used in our demos. See under @code{deployment/config}. + +@quotation + +@strong{Note} + +Expectably, some components will not work just by using default +values, as their work is often interdependent. For example, a +merchant needs to know an exchange URL, or a database name. +@end quotation + +@node Using taler-config,Keying,Configuration format,Configuration +@anchor{taler-exchange-manual using-taler-002dconfig-exchange}@anchor{a}@anchor{taler-exchange-manual using-taler-config}@anchor{b} +@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 ACCOUNT-bank \ + -o WIRE_RESPONSE +$ taler-config -f -s ACCOUNT-bank \ + -o WIRE_RESPONSE +@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. + +@node Keying,Serving,Using taler-config,Configuration +@anchor{taler-exchange-manual id3}@anchor{c}@anchor{taler-exchange-manual keying}@anchor{d} +@section Keying + + +The exchange works with three types of keys: + + +@itemize - + +@item +master key + +@item +sign keys + +@item +denomination keys (see section Coins) + +@item +MASTER_PRIV_FILE: Path to the exchange’s master private file. + +@item +MASTER_PUBLIC_KEY: Must specify the exchange’s master public key. +@end itemize + +@node Serving,Currency,Keying,Configuration +@anchor{taler-exchange-manual id4}@anchor{e}@anchor{taler-exchange-manual serving}@anchor{f} +@section Serving + + +The exchange can serve HTTP over both TCP and UNIX domain socket. + +The following values are to be configured in the section [exchange]: + + +@itemize - + +@item +serve: must be set to tcp to serve HTTP over TCP, or unix to serve +HTTP over a UNIX domain socket + +@item +port: Set to the TCP port to listen on if serve Is tcp. + +@item +unixpath: set to the UNIX domain socket path to listen on if serve Is +unix + +@item +unixpath_mode: number giving the mode with the access permission MASK +for the unixpath (i.e. 660 = rw-rw—-). +@end itemize + +@node Currency,Bank account,Serving,Configuration +@anchor{taler-exchange-manual currency}@anchor{10}@anchor{taler-exchange-manual id5}@anchor{11} +@section Currency + + +The exchange supports only one currency. This data is set under the +respective option currency in section [taler]. + +@node Bank account,Database,Currency,Configuration +@anchor{taler-exchange-manual bank-account}@anchor{12}@anchor{taler-exchange-manual id6}@anchor{13} +@section Bank account + + +To configure a bank account in Taler, we need to furnish four pieces of +information: + + +@itemize - + +@item +The @code{payto://} URL of the bank account, which uniquely idenfies the +account. Examples for such URLs include +@code{payto://sepa/CH9300762011623852957} for a bank account in the +single European payment area (SEPA) or +@code{payto://x-taler-bank/localhost:8080/2} for the 2nd bank account a +the Taler bank demonstrator running at @code{localhost} on port 8080. +The first part of the URL following @code{payto://} (“sepa” or +“x-taler-bank”) is called the wire method. + +@item +A matching wire plugin that implements a protocol to interact with +the banking system. For example, the EBICS plugin can be used for +SEPA transfers, or the “taler-bank” plugin can interact with the +Taler bank demonstrator. A wire plugin only supports one particular +wire method. Thus, you must make sure to pick a plugin that supports +the wire method used in the URL. + +@item +A file containing the signed JSON-encoded bank account details for +the /wire API. This is necessary as Taler supports offline signing +for bank accounts for additional security. + +@item +Finally, the plugin needs to be provided resources for authentication +to the respective banking service. The format in which the +authentication information must be provided depends on the wire +plugin. +@end itemize + +You can configure multiple accounts for an exchange by creating sections +starting with “account-” for the section name. You can ENABLE for each +account whether it should be used, and for what (incoming or outgoing +wire transfers): + +@example +[account-1] +URL = "payto://sepa/CH9300762011623852957" +WIRE_RESPONSE = $@{TALER_CONFIG_HOME@}/account-1.json + +# Currently, only the 'taler_bank' plugin is implemented. +PLUGIN = <plugin_name_here> + +# Use for exchange-aggregator (outgoing transfers) +ENABLE_DEBIT = YES +# Use for exchange-wirewatch (and listed in /wire) +ENABLE_CREDIT = YES + +# Authentication options for the chosen plugin go here. +# (Next sections have examples of authentication mechanisms) +@end example + +The command line tool taler-exchange-wire is used to create the +@code{account-1.json} file. For example, the utility may be invoked as +follows to create all of the WIRE_RESPONSE files (in the locations +specified by the configuration): + +@example +$ taler-exchange-wire +@end example + +The generated file will be echoed by the exchange when serving +/wire @footnote{@w{(3)} +@indicateurl{https://api.taler.net/api-exchange.html#wire-req} +} requests. + +@menu +* Wire plugin “taler_bank”:: +* Wire plugin “ebics”:: +* Wire fee structure:: + +@end menu + +@node Wire plugin “taler_bank”,Wire plugin “ebics”,,Bank account +@anchor{taler-exchange-manual wire-plugin-0060-0060taler-005fbank-0027-0027}@anchor{14}@anchor{taler-exchange-manual wire-plugin-taler-bank}@anchor{15} +@subsection Wire plugin “taler_bank” + + +x-taler-bank +taler_bank plugin +The @code{taler_bank} plugin implements the wire method “x-taler-bank”. + +The format of the @code{payto://} URL is +@code{payto://x-taler-bank/HOSTNAME[:PORT]}. + +For basic authentication, the @code{taler_bank} plugin only supports simple +password-based authentication. For this, the configuration must contain +the “USERNAME” and “PASSWORD” of the respective account at the bank. + +@example +[account-1] + +# Bank account details here.. +# .. + +# Authentication options for the taler_bank plugin below: + +TALER_BANK_AUTH_METHOD = basic +USERNAME = exchange +PASSWORD = super-secure +@end example + +@node Wire plugin “ebics”,Wire fee structure,Wire plugin “taler_bank”,Bank account +@anchor{taler-exchange-manual wire-plugin-0060-0060ebics-0027-0027}@anchor{16}@anchor{taler-exchange-manual wire-plugin-ebics}@anchor{17} +@subsection Wire plugin “ebics” + + +The “ebics” wire plugin is not fully implemented and today does not +support actual wire transfers. + +@quotation + +@strong{Note} + +The rationale behind having multiple bank accounts is that the +exchange operator, as a security measure, may want to instruct the +bank that the incoming bank account is only supposed to @emph{receive} +money. +@end quotation + +@node Wire fee structure,,Wire plugin “ebics”,Bank account +@anchor{taler-exchange-manual id8}@anchor{18}@anchor{taler-exchange-manual wire-fee-structure}@anchor{19} +@subsection Wire fee structure + + +wire fee +fee +For each wire method (“sepa” or “x-taler-wire”, but not per plugin!) the +exchange configuration must specify applicable wire fees. This is done +in configuration sections of the format @code{fees-METHOD}. There are two +types of fees, simple wire fees and closing fees. Wire fees apply +whenever the aggregator transfers funds to a merchant. Closing fees +apply whenever the exchange closes a reserve (sending back funds to the +customer). The fees must be constant for a full year, which is specified +as part of the name of the option. + +@example +[fees-iban] +WIRE-FEE-2018 = EUR:0.01 +WIRE-FEE-2019 = EUR:0.01 +CLOSING-FEE-2018 = EUR:0.01 +CLOSING-FEE-2019 = EUR:0.01 + +[fees-x-taler-bank] +WIRE-FEE-2018 = KUDOS:0.01 +WIRE-FEE-2019 = KUDOS:0.01 +CLOSING-FEE-2018 = KUDOS:0.01 +CLOSING-FEE-2019 = KUDOS:0.01 +@end example + +@node Database,Coins denomination keys,Bank account,Configuration +@anchor{taler-exchange-manual database}@anchor{1a}@anchor{taler-exchange-manual id9}@anchor{1b} +@section Database + + +The option db under section [exchange] gets the DB backend’s name the +exchange is going to use. So far, only db = postgres is supported. After +choosing the backend, it is mandatory to supply the connection string +(namely, the database name). This is possible in two ways: + + +@itemize - + +@item +via an environment variable: TALER_EXCHANGEDB_POSTGRES_CONFIG. + +@item +via configuration option CONFIG, under section [exchangedb-BACKEND]. +For example, the demo exchange is configured as follows: +@end itemize + +@example +[exchange] +... +DB = postgres +... + +[exchangedb-postgres] +CONFIG = postgres:///talerdemo +@end example + +@node Coins denomination keys,Keys duration,Database,Configuration +@anchor{taler-exchange-manual coins-denomination-keys}@anchor{1c}@anchor{taler-exchange-manual id10}@anchor{1d} +@section Coins (denomination keys) + + +Sections specifying denomination (coin) information start with @code{coin_}. +By convention, the name continues with "$CURRENCY_[$SUBUNIT]_$VALUE", +i.e. @code{[coin_eur_ct_10]} for a 10 cent piece. However, only the @code{coin_} +prefix is mandatory. Each @code{coin_}-section must then have the following +options: + + +@itemize - + +@item +value: How much is the coin worth, the format is +CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is "EUR:0.10". + +@item +duration_withdraw: How long can a coin of this type be withdrawn? +This limits the losses incurred by the exchange when a denomination +key is compromised. + +@item +duration_overlap: What is the overlap of the withdrawal timespan for +this coin type? + +@item +duration_spend: How long is a coin of the given type valid? Smaller +values result in lower storage costs for the exchange. + +@item +fee_withdraw: What does it cost to withdraw this coin? Specified +using the same format as value. + +@item +fee_deposit: What does it cost to deposit this coin? Specified using +the same format as value. + +@item +fee_refresh: What does it cost to refresh this coin? Specified using +the same format as value. + +@item +rsa_keysize: How many bits should the RSA modulus (product of the two +primes) have for this type of coin. +@end itemize + +@node Keys duration,,Coins denomination keys,Configuration +@anchor{taler-exchange-manual id11}@anchor{1e}@anchor{taler-exchange-manual keys-duration}@anchor{1f} +@section Keys duration + + +Both signkeys and denom keys have a starting date. The option +lookahead_provide, under section [exchange], is such that only keys +whose starting date is younger than lookahead_provide will be issued by +the exchange. + +signkeys. The option lookahead_sign is such that, being t the time when +taler-exchange-keyup is run, taler-exchange-keyup will generate n +signkeys, where t + (n * signkey_duration) = t + lookahead_sign. In +other words, we generate a number of keys which is sufficient to cover a +period of lookahead_sign. As for the starting date, the first generated +key will get a starting time of t, and the j-th key will get a starting +time of x + signkey_duration, where x is the starting time of the +(j-1)-th key. + +denom keys. The option lookahead_sign is such that, being t the time +when taler-exchange-keyup is run, taler-exchange-keyup will generate n +denom keys for each denomination, where t + (n * duration_withdraw) = t ++ lookahead_sign. In other words, for each denomination, we generate a +number of keys which is sufficient to cover a period of lookahead_sign. +As for the starting date, the first generated key will get a starting +time of t, and the j-th key will get a starting time of x + +duration_withdraw, where x is the starting time of the (j-1)-th key. + +To change these settings, edit the following values in section +[exchange]: + + +@itemize - + +@item +SIGNKEY_DURATION: How long should one signing key be used? + +@item +LOOKAHEAD_SIGN: How much time we want to cover with our signing keys? +Note that if SIGNKEY_DURATION is bigger than LOOKAHEAD_SIGN, +@code{taler-exchange-keyup} will generate a quantity of signing keys +which is sufficient to cover all the gap. +@end itemize + +@node Deployment,Diagnostics,Configuration,Top +@anchor{taler-exchange-manual deployment}@anchor{20}@anchor{taler-exchange-manual id12}@anchor{21} +@chapter Deployment + + +@menu +* Keys generation:: +* Database upgrades:: + +@end menu + +@node Keys generation,Database upgrades,,Deployment +@anchor{taler-exchange-manual id13}@anchor{22}@anchor{taler-exchange-manual keys-generation}@anchor{23} +@section Keys generation + + +Once the configuration is properly set up, all the keys can be generated +by the tool @code{taler-exchange-keyup}. The following command generates +denomkeys and signkeys, plus the "blob" that is to be signed by the +auditor. + +@example +taler-exchange-keyup -o blob +@end example + +@emph{blob} contains data about denomkeys that the exchange operator needs to +get signed by every auditor he wishes (or is forced to) work with. + +In a normal scenario, an auditor must have some way of receiving the +blob to sign (Website, manual delivery, ..). Nonetheless, the exchange +admin can fake an auditor signature — for testing purposes — by running +the following command + +@example +taler-auditor-sign -m EXCHANGE_MASTER_PUB -r BLOB -u AUDITOR_URL -o OUTPUT_FILE +@end example + +Those arguments are all mandatory. + + +@itemize - + +@item +@code{EXCHANGE_MASTER_PUB} the base32 Crockford-encoded exchange’s +master public key. Tipically, this value lies in the configuration +option @code{[exchange]/master_public_key}. + +@item +@code{BLOB} the blob generated in the previous step. + +@item +@code{AUDITOR_URL} the URL that identifies the auditor. + +@item +@code{OUTPUT_FILE} where on the disk the signed blob is to be saved. +@end itemize + +@code{OUTPUT_FILE} must then be copied into the directory specified by the +option @code{AUDITOR_BASE_DIR} under the section @code{[exchangedb]}. Assuming +@code{AUDITOR_BASE_DIR = $@{HOME@}/.local/share/taler/auditors}, the +following command will "add" the auditor identified by @code{AUDITOR_URL} +to the exchange. + +@example +cp OUTPUT_FILE $@{HOME@}/.local/share/taler/auditors +@end example + +If the auditor has been correctly added, the exchange’s @code{/keys} +response must contain an entry in the @code{auditors} array mentioning the +auditor’s URL. + +@node Database upgrades,,Keys generation,Deployment +@anchor{taler-exchange-manual database-upgrades}@anchor{24}@anchor{taler-exchange-manual id14}@anchor{25} +@section Database upgrades + + +Currently, there is no way to upgrade the database between Taler +versions. + +The exchange database can be re-initialized using: + +@example +$ taler-exchange-dbinit -r +@end example + +However, running this command will result in all data in the database +being lost, which may result in significant financial liabilities as the +exchange can then not detect double-spending. Hence this operation must +not be performed in a production system. + +@node Diagnostics,,Deployment,Top +@anchor{taler-exchange-manual diagnostics}@anchor{26}@anchor{taler-exchange-manual id15}@anchor{27} +@chapter Diagnostics + + +This chapter includes various (very unpolished) sections on specific +topics that might be helpful to understand how the exchange operates, +which files should be backed up. The information may also be helpful for +diagnostics. + +@menu +* Reserve management:: +* Database Scheme:: +* Signing key storage:: +* Denomination key storage:: +* Auditor signature storage:: + +@end menu + +@node Reserve management,Database Scheme,,Diagnostics +@anchor{taler-exchange-manual id16}@anchor{28}@anchor{taler-exchange-manual reserve-management}@anchor{29} +@section Reserve management + + +Incoming transactions to the exchange’s provider result in the creation +or update of reserves, identified by their reserve key. The command line +tool taler-exchange-reservemod allows create and add money to reserves +in the exchange’s database. + +@node Database Scheme,Signing key storage,Reserve management,Diagnostics +@anchor{taler-exchange-manual database-scheme}@anchor{2a}@anchor{taler-exchange-manual id17}@anchor{2b} +@section Database Scheme + + +The exchange database must be initialized using taler-exchange-dbinit. +This tool creates the tables required by the Taler exchange to operate. +The tool also allows you to reset the Taler exchange database, which is +useful for test cases but should never be used in production. Finally, +taler-exchange-dbinit has a function to garbage collect a database, +allowing administrators to purge records that are no longer required. + +The database scheme used by the exchange look as follows: + +@image{taler-exchange-figures/exchange-db,,,,png} + +@node Signing key storage,Denomination key storage,Database Scheme,Diagnostics +@anchor{taler-exchange-manual id18}@anchor{2c}@anchor{taler-exchange-manual signing-key-storage}@anchor{2d} +@section Signing key storage + + +The private online signing keys of the exchange are stored in a +subdirectory "signkeys/" of the "KEYDIR" which is an option in the +"[exchange]" section of the configuration file. The filename is the +starting time at which the signing key can be used in microseconds since +the Epoch. The file format is defined by the struct +TALER_EXCHANGEDB_PrivateSigningKeyInformationP: + +@example +struct TALER_EXCHANGEDB_PrivateSigningKeyInformationP @{ + struct TALER_ExchangePrivateKeyP signkey_priv; + struct TALER_ExchangeSigningKeyValidityPS issue; +@}; +@end example + +@node Denomination key storage,Auditor signature storage,Signing key storage,Diagnostics +@anchor{taler-exchange-manual denomination-key-storage}@anchor{2e}@anchor{taler-exchange-manual id19}@anchor{2f} +@section Denomination key storage + + +The private denomination keys of the exchange are store in a +subdirectory "denomkeys/" of the "KEYDIR" which is an option in the +"[exchange]" section of the configuration file. "denomkeys/" contains +further subdirectories, one per denomination. The specific name of the +subdirectory under "denomkeys/" is ignored by the exchange. However, the +name is important for the "taler-exchange-keyup" tool that generates the +keys. The tool combines a human-readable encoding of the denomination +(i.e. for EUR:1.50 the prefix would be "EUR_1_5-", or for EUR:0.01 the +name would be "EUR_0_01-") with a postfix that is a truncated +Crockford32 encoded hash of the various attributes of the denomination +key (relative validity periods, fee structure and key size). Thus, if +any attributes of a coin change, the name of the subdirectory will also +change, even if the denomination remains the same. + +Within this subdirectory, each file represents a particular denomination +key. The filename is the starting time at which the signing key can be +used in microseconds since the Epoch. The format on disk begins with a +struct TALER_EXCHANGEDB_DenominationKeyInformationP giving the +attributes of the denomination key and the associated signature with the +exchange’s long-term offline key: + +@example +struct TALER_EXCHANGEDB_DenominationKeyInformationP @{ + struct TALER_MasterSignatureP signature; + struct TALER_DenominationKeyValidityPS properties; +@}; +@end example + +This is then followed by the variable-size RSA private key in +libgcrypt’s S-expression format, which can be decoded using +GNUNET_CRYPTO_rsa_private_key_decode(). + +@menu +* Revocations:: + +@end menu + +@node Revocations,,,Denomination key storage +@anchor{taler-exchange-manual id20}@anchor{30}@anchor{taler-exchange-manual revocations}@anchor{31} +@subsection Revocations + + +When an exchange goes out of business or detects that the private key of +a denomination key pair has been compromised, it may revoke some or all +of its denomination keys. At this point, the hashes of the revoked keys +must be returned as part of the @code{/keys} response under “payback”. +Wallets detect this, and then return unspent coins of the respective +denomination key using the @code{/payback} API. + +When a denomination key is revoked, a revocation file is placed into the +respective subdirectory of “denomkeys/”. The file has the same prefix as +the file that stores the struct +TALER_EXCHANGEDB_DenominationKeyInformationP information, but is +followed by the “.rev” suffix. It contains a 64-byte EdDSA signature +made with the master key of the exchange with purpose +@code{TALER_SIGNATURE_MASTER_DENOMINATION_KEY_REVOKED}. If such a file is +present, the exchange must check the signature and if it is valid treat +the respective denomination key as revoked. + +Revocation files can be generated using the @code{taler-exchange-keyup} +command-line tool using the @code{-r} option. The Taler auditor will +instruct operators to generate revocations if it detects a key +compromise (which is possible more coins of a particular denomination +were deposited than issued). + +It should be noted that denomination key revocations should only happen +under highly unusual (“emergency”) conditions and not under normal +conditions. + +@node Auditor signature storage,,Denomination key storage,Diagnostics +@anchor{taler-exchange-manual auditor-signature-storage}@anchor{32}@anchor{taler-exchange-manual id21}@anchor{33} +@section Auditor signature storage + + +Signatures from auditors are stored in the directory specified in the +exchange configuration section "exchangedb" under the option +"AUDITOR_BASE_DIR". The exchange does not care about the specific names +of the files in this directory. + +Each file must contain a header with the public key information of the +auditor, the master public key of the exchange, and the number of signed +denomination keys: + +@example +struct AuditorFileHeaderP @{ + struct TALER_AuditorPublicKeyP apub; + struct TALER_MasterPublicKeyP mpub; + uint32_t dki_len; +@}; +@end example + +This is then followed by dki_len signatures of the auditor of type +struct TALER_AuditorSignatureP, which are then followed by another +dki_len blocks of type struct TALER_DenominationKeyValidityPS. The +auditor’s signatures must be signatures over the information of the +corresponding denomination key validity structures embedded in a struct +TALER_ExchangeKeyValidityPS structure using the +TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS purpose. + +@c %**end of body +@bye diff --git a/texinfo/taler-merchant-api-tutorial-figures/arch-api.png b/texinfo/taler-merchant-api-tutorial-figures/arch-api.png Binary files differnew file mode 100644 index 00000000..8004f790 --- /dev/null +++ b/texinfo/taler-merchant-api-tutorial-figures/arch-api.png diff --git a/texinfo/taler-merchant-api-tutorial-figures/exchange-db.png b/texinfo/taler-merchant-api-tutorial-figures/exchange-db.png Binary files differnew file mode 100644 index 00000000..421e5941 --- /dev/null +++ b/texinfo/taler-merchant-api-tutorial-figures/exchange-db.png diff --git a/texinfo/taler-merchant-api-tutorial.texi b/texinfo/taler-merchant-api-tutorial.texi new file mode 100644 index 00000000..b49eeefe --- /dev/null +++ b/texinfo/taler-merchant-api-tutorial.texi @@ -0,0 +1,945 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename taler-merchant-api-tutorial.info +@documentencoding UTF-8 +@ifinfo +@*Generated by Sphinx 2.2.0.@* +@end ifinfo +@settitle Taler Merchant API Tutorial +@defindex ge +@paragraphindent 0 +@exampleindent 4 +@finalout +@dircategory CATEGORY +@direntry +* MENU ENTRY: (taler-merchant-api-tutorial.info). DESCRIPTION +@end direntry + +@definfoenclose strong,`,' +@definfoenclose emph,`,' +@c %**end of header + +@copying +@quotation +GNU Taler 0.6.0pre1, Sep 18, 2019 + +GNU Taler team + +Copyright @copyright{} 2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+) +@end quotation + +@end copying + +@titlepage +@title Taler Merchant API Tutorial +@insertcopying +@end titlepage +@contents + +@c %** start of user preamble + +@c %** end of user preamble + +@ifnottex +@node Top +@top Taler Merchant API Tutorial +@insertcopying +@end ifnottex + +@c %**start of body +@anchor{taler-merchant-api-tutorial doc}@anchor{0} +@menu +* Introduction:: +* Accepting a Simple Payment:: +* Giving Refunds:: +* Giving Customers Tips:: +* Advanced topics:: + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* About GNU Taler:: +* About this tutorial:: +* Architecture overview:: +* Public Sandbox Backend and Authentication:: +* Merchant Instances:: + +Accepting a Simple Payment + +* Creating an Order for a Payment:: +* Checking Payment Status and Prompting for Payment:: + +Advanced topics + +* Detecting the Presence of the Taler Wallet:: +* Integration with the Back Office:: +* Session-Bound Payments:: +* Product Identification:: +* The Taler Order Format:: + +Detecting the Presence of the Taler Wallet + +* Presence detection without JavaScript:: +* Detection with JavaScript:: + +@end detailmenu +@end menu + +@node Introduction,Accepting a Simple Payment,Top,Top +@anchor{taler-merchant-api-tutorial gnu-taler-merchant-api-tutorial}@anchor{1}@anchor{taler-merchant-api-tutorial introduction}@anchor{2} +@chapter Introduction + + +@menu +* About GNU Taler:: +* About this tutorial:: +* Architecture overview:: +* Public Sandbox Backend and Authentication:: +* Merchant Instances:: + +@end menu + +@node About GNU Taler,About this tutorial,,Introduction +@anchor{taler-merchant-api-tutorial about-gnu-taler}@anchor{3} +@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). + +@node About this tutorial,Architecture overview,About GNU Taler,Introduction +@anchor{taler-merchant-api-tutorial about-this-tutorial}@anchor{4} +@section About this tutorial + + +This tutorial addresses how to process payments using the GNU Taler +merchant Backend. This chapter explains some basic concepts. In the +second chapter, you will learn how to do basic payments. + +This version of the tutorial has examples for Python3. It uses the +requests library for HTTP requests. Versions for other +languages/environments are available as well. + +If you want to look at some simple, running examples, check out these: + + +@itemize - + +@item +The essay merchant@footnote{https://git.taler.net/blog.git/tree/talerblog/blog/blog.py} +that sells single chapters of a book. + +@item +The donation page@footnote{https://git.taler.net/donations.git/tree/talerdonations/donations/donations.py} +that accepts donations for software projects and gives donation +receipts. + +@item +The +survey@footnote{https://git.taler.net/survey.git/tree/talersurvey/survey/survey.py} +that gives users who answer a question a small reward. +@end itemize + +@node Architecture overview,Public Sandbox Backend and Authentication,About this tutorial,Introduction +@anchor{taler-merchant-api-tutorial architecture-overview}@anchor{5} +@section Architecture overview + + +The Taler software stack for a merchant consists of the following main +components: + + +@itemize - + +@item +frontend +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 tutorial describes how to +develop a Taler frontend. + +@item +backend +A Taler-specific payment backend which makes it easy for the frontend +to process financial transactions with Taler. For this tutorial, you +will use a public sandbox backend. For production use, you must +either set up your own backend or ask another person to do so for +you. +@end itemize + +The following image illustrates the various interactions of these key +components: + + +@image{taler-merchant-api-tutorial-figures/arch-api,,,image0,png} + + +The backend provides the cryptographic protocol support, stores +Taler-specific financial information 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 are +encapsulated within the Taler backend. + +Some functionality of the backend (the “public interface“) is also +exposed to the customer’s browser directly. In the HTTP API, all public +endpoints are prefixed with @code{/public/}. + +@node Public Sandbox Backend and Authentication,Merchant Instances,Architecture overview,Introduction +@anchor{taler-merchant-api-tutorial public-sandbox-backend-and-authentication}@anchor{6} +@section Public Sandbox Backend and Authentication + + +sandbox +authorization +How the frontend authenticates to the Taler backend depends on the +configuration. See Taler Merchant Operating Manual. + +The public sandbox backend @indicateurl{https://backend.demo.taler.net/} uses an API +key in the @code{Authorization} header. The value of this header must be +@code{ApiKey sandbox} for the public sandbox backend. + +@example +>>> import requests +>>> requests.get("https://backend.demo.taler.net", +... headers=@{"Authorization": "ApiKey sandbox"@}) +<Response [200]> +@end example + +If an HTTP status code other than 200 is returned, something went wrong. +You should figure out what the problem is before continuing with this +tutorial. + +The sandbox backend @indicateurl{https://backend.demo.taler.net/} uses @code{KUDOS} as an +imaginary currency. Coins denominated in @code{KUDOS} can be withdrawn from +@indicateurl{https://bank.demo.taler.net/}. + +@node Merchant Instances,,Public Sandbox Backend and Authentication,Introduction +@anchor{taler-merchant-api-tutorial merchant-instances}@anchor{7} +@section Merchant Instances + + +instance +The same Taler merchant backend server can be used by multiple separate +merchants that are separate business entities. Each of these separate +business entities is called a @emph{merchant instance}, and is identified by +an alphanumeric @emph{instance id}. If the instance is omitted, the instance +id @code{default} is assumed. + +The following merchant instances are configured on +@indicateurl{https://backend.demo.taler.net/}: + + +@itemize - + +@item +@code{GNUnet} (The GNUnet project) + +@item +@code{FSF} (The Free Software Foundation) + +@item +@code{Tor} (The Tor Project) + +@item +@code{default} (Kudos Inc.) +@end itemize + +Note that these are fictional merchants used for our demonstrators and +not affiliated with or officially approved by the respective projects. + +@node Accepting a Simple Payment,Giving Refunds,Introduction,Top +@anchor{taler-merchant-api-tutorial accepting-a-simple-payment}@anchor{8}@anchor{taler-merchant-api-tutorial id1}@anchor{9} +@chapter Accepting a Simple Payment + + +@menu +* Creating an Order for a Payment:: +* Checking Payment Status and Prompting for Payment:: + +@end menu + +@node Creating an Order for a Payment,Checking Payment Status and Prompting for Payment,,Accepting a Simple Payment +@anchor{taler-merchant-api-tutorial creating-an-order-for-a-payment}@anchor{a} +@section Creating an Order for a Payment + + +order +Payments in Taler revolve around an @emph{order}, which is a machine-readable +description of the business transaction for which the payment is to be +made. Before accepting a Taler payment as a merchant you must create +such an order. + +This is done by posting a JSON object to the backend’s @code{/order} API +endpoint. At least the following fields must be given: + + +@itemize - + +@item +amount: The amount to be paid, as a string in the format +@code{CURRENCY:DECIMAL_VALUE}, for example @code{EUR:10} for 10 Euros or +@code{KUDOS:1.5} for 1.5 KUDOS. + +@item +summary: A human-readable summary for what the payment is about. The +summary should be short enough to fit into titles, though no hard +limit is enforced. + +@item +fulfillment_url: A URL that will be displayed once the payment is +completed. For digital goods, this should be a page that displays the +product that was purchased. On successful payment, the wallet +automatically appends the @code{order_id} as a query parameter, as well +as the @code{session_sig} for session-bound payments (discussed later). +@end itemize + +Orders can have many more fields, see @ref{b,,The Taler Order Format}. + +After successfully @code{POST}ing to @code{/order}, an @code{order_id} will be +returned. Together with the merchant @code{instance}, the order id uniquely +identifies the order within a merchant backend. + +@example +>>> import requests +>>> order = dict(order=dict(amount="KUDOS:10", +... summary="Donation", +... fulfillment_url="https://example.com/thanks.html")) +>>> order_resp = requests.post("https://backend.demo.taler.net/order", json=order, +... headers=@{"Authorization": "ApiKey sandbox"@}) +<Response [200]> +@end example + +The backend will fill in some details missing in the order, such as the +address of the merchant instance. The full details are called the +@emph{contract terms}. contract terms + +@node Checking Payment Status and Prompting for Payment,,Creating an Order for a Payment,Accepting a Simple Payment +@anchor{taler-merchant-api-tutorial checking-payment-status-and-prompting-for-payment}@anchor{c} +@section Checking Payment Status and Prompting for Payment + + +The status of a payment can be checked with the @code{/check-payment} +endpoint. If the payment is yet to be completed by the customer, +@code{/check-payment} will give the frontend a URL (the +payment_redirect_url) that will trigger the customer’s wallet to execute +the payment. + +Note that the only way to obtain the payment_redirect_url is to check +the status of the payment, even if you know that the user did not pay +yet. + +@example +>>> import requests +>>> r = requests.get("https://backend.demo.taler.net/check-payment", +... params=dict(order_id=order_resp.json()["order_id"]), +... headers=@{"Authorization": "ApiKey sandbox"@}) +>>> print(r.json()) +@end example + +If the paid field in the response is @code{true}, the other fields in the +response will be different. Once the payment was completed by the user, +the response will contain the following fields: + + +@itemize - + +@item +paid: Set to true. + +@item +contract_terms: The full contract terms of the order. + +@item +refunded: @code{true} if a (possibly partial) refund was granted for +this purchase. + +@item +refunded_amount: Amount that was refunded + +@item +last_session_id: Last session ID used by the customer’s wallet. See +@ref{d,,Session-Bound Payments}. +@end itemize + +Once the frontend has confirmed that the payment was successful, it +usually needs to trigger the business logic for the merchant to fulfill +the merchant’s obligations under the contract. + +@node Giving Refunds,Giving Customers Tips,Accepting a Simple Payment,Top +@anchor{taler-merchant-api-tutorial giving-refunds}@anchor{e}@anchor{taler-merchant-api-tutorial id2}@anchor{f} +@chapter Giving Refunds + + +refunds +A refund in GNU Taler is a way to “undo” a payment. It needs to be +authorized by the merchant. Refunds can be for any fraction of the +original amount paid, but they cannot exceed the original payment. +Refunds are time-limited and can only happen while the exchange holds +funds for a particular payment in escrow. The time during which a refund +is possible can be controlled by setting the @code{refund_deadline} in an +order. The default value for this refund deadline is specified in the +configuration of the merchant’s backend. + +The frontend can instruct the merchant backend to authorize a refund by +@code{POST}ing to the @code{/refund} endpoint. + +The refund request JSON object has the following fields: + + +@itemize - + +@item +order_id: Identifies for which order a customer should be refunded. + +@item +instance: Merchant instance to use. + +@item +refund: Amount to be refunded. If a previous refund was authorized +for the same order, the new amount must be higher, otherwise the +operation has no effect. The value indicates the total amount to be +refunded, @emph{not} an increase in the refund. + +@item +reason: Human-readable justification for the refund. The reason is +only used by the Back Office and is not exposed to the customer. +@end itemize + +If the request is successful (indicated by HTTP status code 200), the +response includes a @code{refund_redirect_url}. The frontend must redirect +the customer’s browser to that URL to allow the refund to be processed +by the wallet. + +This code snipped illustrates giving a refund: + +@example +>>> import requests +>>> refund_req = dict(order_id="2018.058.21.46.06-024C85K189H8P", +... refund="KUDOS:10", +... instance="default", +... reason="Customer did not like the product") +>>> requests.post("https://backend.demo.taler.net/refund", json=refund_req, +... headers=@{"Authorization": "ApiKey sandbox"@}) +<Response [200]> +@end example + +@node Giving Customers Tips,Advanced topics,Giving Refunds,Top +@anchor{taler-merchant-api-tutorial giving-customers-tips}@anchor{10}@anchor{taler-merchant-api-tutorial id3}@anchor{11} +@chapter Giving Customers Tips + + +tips +GNU Taler allows Web sites to grant small amounts directly to the +visitor. The idea is that some sites may want incentivize actions such +as filling out a survey or trying a new feature. It is important to note +that tips are not enforceable for the visitor, as there is no contract. +It is simply a voluntary gesture of appreciation of the site to its +visitor. However, once a tip has been granted, the visitor obtains full +control over the funds provided by the site. + +The “merchant” backend of the site must be properly configured for +tipping, and sufficient funds must be made available for tipping See +Taler Merchant Operating Manual. + +To check if tipping is configured properly and if there are sufficient +funds available for tipping, query the @code{/tip-query} endpoint: + +@example +>>> import requests +>>> requests.get("https://backend.demo.taler.net/tip-query?instance=default", +... headers=@{"Authorization": "ApiKey sandbox"@}) +<Response [200]> +@end example + +authorize tip +To authorize a tip, @code{POST} to @code{/tip-authorize}. The following fields +are recognized in the JSON request object: + + +@itemize - + +@item +amount: Amount that should be given to the visitor as a tip. + +@item +instance: Merchant instance that grants the tip (each instance may +have its own independend tipping funds configured). + +@item +justification: Description of why the tip was granted. Human-readable +text not exposed to the customer, but used by the Back Office. + +@item +next_url: The URL that the user’s browser should be redirected to by +the wallet, once the tip has been processed. +@end itemize + +The response from the backend contains a @code{tip_redirect_url}. The +customer’s browser must be redirected to this URL for the wallet to pick +up the tip. pick up tip + +This code snipped illustrates giving a tip: + +@example +>>> import requests +>>> tip_req = dict(amount="KUDOS:0.5", +... instance="default", +... justification="User filled out survey", +... next_url="https://merchant.com/thanks.html") +>>> requests.post("https://backend.demo.taler.net/tip-authorize", json=tip_req, +... headers=@{"Authorization": "ApiKey sandbox"@}) +<Response [200]> +@end example + +@node Advanced topics,,Giving Customers Tips,Top +@anchor{taler-merchant-api-tutorial advanced-topics}@anchor{12}@anchor{taler-merchant-api-tutorial id4}@anchor{13} +@chapter Advanced topics + + +@menu +* Detecting the Presence of the Taler Wallet:: +* Integration with the Back Office:: +* Session-Bound Payments:: +* Product Identification:: +* The Taler Order Format:: + +@end menu + +@node Detecting the Presence of the Taler Wallet,Integration with the Back Office,,Advanced topics +@anchor{taler-merchant-api-tutorial detecting-the-presence-of-the-taler-wallet}@anchor{14}@anchor{taler-merchant-api-tutorial id5}@anchor{15} +@section Detecting the Presence of the Taler Wallet + + +Taler offers ways to detect whether a user has the wallet installed in +their browser. This allows Web sites to adapt accordingly. Note that not +all platforms can do presence detection reliably. Some platforms might +have a Taler wallet installed as a separate App instead of using a Web +extension. In these cases, presence detection will fail. Thus, sites may +want to allow users to request Taler payments even if a wallet could not +be detected, especially for visitors using mobiles. + +@menu +* Presence detection without JavaScript:: +* Detection with JavaScript:: + +@end menu + +@node Presence detection without JavaScript,Detection with JavaScript,,Detecting the Presence of the Taler Wallet +@anchor{taler-merchant-api-tutorial presence-detection-without-javascript}@anchor{16} +@subsection Presence detection without JavaScript + + +Presence detection without JavaScript is based on CSS classes. You can +hide or show elements selectively depending on whether the wallet is +detected or not. + +In order to work correctly, a special fallback stylesheet must be +included that will be used when the wallet is not present. The +stylesheet can be put into any file, but must be included via a @code{link} +tag with the @code{id} attribute set to @code{taler-presence-stylesheet}. If a +wallet is present, it will “hijack” this stylesheet to change how +elements with the following classes are rendered: + +The following CSS classes can be used: + + +@table @asis + +@item @code{taler-installed-hide} + +A CSS rule will set the @code{display} property for this class to +@code{none} once the Taler wallet is installed and enabled. If the +wallet is not installed, @code{display} will be @code{inherit}. + +@item @code{taler-installed-show} + +A CSS rule will set the @code{display} property for this class to +@code{inherit} once the Taler wallet is installed and enabled. If the +wallet is not installed, @code{display} will be @code{none}. +@end table + +The following is a complete example: + +@example +<!DOCTYPE html> +<html data-taler-nojs="true"> + <head> + <title>Tutorial</title> + <link rel="stylesheet" + type="text/css" + href="/web-common/taler-fallback.css" + id="taler-presence-stylesheet" /> + </head> + <body> + <p class="taler-installed-hide"> + No wallet found. + </p> + <p class="taler-installed-show"> + Wallet found! + </p> + </body> +</html> +@end example + +The @code{taler-fallback.css} is part of the Taler’s @emph{web-common} +repository, available at +@indicateurl{https://git.taler.net/web-common.git/tree/taler-fallback.css}. You may +have to adjust the @code{href} attribute in the HTML code above to point to +the correct location of the @code{taler-fallback.css} file on your Web +site. + +@node Detection with JavaScript,,Presence detection without JavaScript,Detecting the Presence of the Taler Wallet +@anchor{taler-merchant-api-tutorial detection-with-javascript}@anchor{17} +@subsection Detection with JavaScript + + +The following functions are defined in the @code{taler} namespace of the +@code{taler-wallet-lib} helper library available at +@indicateurl{https://git.taler.net/web-common.git/tree/taler-wallet-lib.js}. + + +@table @asis + +@item @code{onPresent(callback: () => void)} + +Adds a callback to be called when support for Taler payments is +detected. + +@item @code{onAbsent(callback: () => void)} + +Adds a callback to be called when support for Taler payments is +disabled. +@end table + +Note that the registered callbacks may be called more than once. This +may happen if a user disables or enables the wallet in the browser’s +extension settings while a shop’s frontend page is open. + +@node Integration with the Back Office,Session-Bound Payments,Detecting the Presence of the Taler Wallet,Advanced topics +@anchor{taler-merchant-api-tutorial id6}@anchor{18}@anchor{taler-merchant-api-tutorial integration-with-the-back-office}@anchor{19} +@section Integration with the Back Office + + +Taler ships a Back Office application as a stand-alone Web application. +The Back Office has its own documentation at +@indicateurl{https://docs.taler.net/backoffice/html/manual.html}. + +Developers wishing to tightly integrate back office support for +Taler-based payments into an existing back office application should +focus on the wire transfer tracking and transaction history sections of +the Taler Backend API specification at +@indicateurl{https://docs.taler.net/api/api-merchant.html} + +@node Session-Bound Payments,Product Identification,Integration with the Back Office,Advanced topics +@anchor{taler-merchant-api-tutorial session-002dbound-payments}@anchor{1a}@anchor{taler-merchant-api-tutorial session-bound-payments}@anchor{1b} +@section Session-Bound Payments + + +session +Sometimes checking if an order has been paid for is not enough. For +example, when selling access to online media, the publisher may want to +be paid for exactly the same product by each customer. Taler supports +this model by allowing the mechant to check whether the “payment +receipt” is available on the user’s current device. This prevents users +from easily sharing media access by transmitting a link to the +fulfillment page. Of course sophisticated users could share payment +receipts as well, but this is not as easy as sharing a link, and in this +case they are more likely to just share the media directly. + +To use this feature, the merchant must first assign the user’s current +browser an ephemeral @code{session_id}, usually via a session cookie. When +executing or re-playing a payment, the wallet will receive an additional +signature (@code{session_sig}). This signature certifies that the wallet +showed a payment receipt for the respective order in the current +session. cookie + +Session-bound payments are triggerd by passing the @code{session_id} +parameter to the @code{/check-payment} endpoint. The wallet will then +redirect to the fulfillment page, but include an additional +@code{session_sig} parameter. The frontend can query @code{/check-payment} +with both the @code{session_id} and the @code{session_sig} to verify that the +signature is correct. + +The last session ID that was successfuly used to prove that the payment +receipt is in the user’s wallet is also available as @code{last_session_id} +in the response to @code{/check-payment}. + +@node Product Identification,The Taler Order Format,Session-Bound Payments,Advanced topics +@anchor{taler-merchant-api-tutorial id7}@anchor{1c}@anchor{taler-merchant-api-tutorial product-identification}@anchor{1d} +@section Product Identification + + +resource url +In some situations the user may have paid for some digital good, but the +frontend does not know the exact order ID, and thus cannot instruct the +wallet to reveil the existing payment receipt. This is common for simple +shops without a login system. In this case, the user would be prompted +for payment again, even though they already purchased the product. + +To allow the wallet to instead find the existing payment receipt, the +shop must use a unique fulfillment URL for each product. Then, the +frontend must provide an additional @code{resource_url} parameter to to +@code{/check-payment}. It should identify this unique fulfillment URL for +the product. The wallet will then check whether it has paid for a +contract with the same @code{resource_url} before, and if so replay the +previous payment. + +@node The Taler Order Format,,Product Identification,Advanced topics +@anchor{taler-merchant-api-tutorial id8}@anchor{1e}@anchor{taler-merchant-api-tutorial the-taler-order-format}@anchor{1f} +@section The Taler Order Format + + +A Taler order can specify many details about the payment. This section +describes each of the fields in depth. + +Financial amounts are always specified as a string in the format +@code{"CURRENCY:DECIMAL_VALUE"}. + + +@table @asis + +@item amount + +amount +Specifies the total amount to be paid to the merchant by the +customer. + +@item max_fee + +fees +maximum deposit fee +This is the maximum total amount of deposit fees that the merchant is +willing to pay. If the deposit fees for the coins exceed this amount, +the customer has to include it in the payment total. The fee is +specified using the same triplet used for amount. + +@item max_wire_fee + +fees +maximum wire fee +Maximum wire fee accepted by the merchant (customer share to be +divided by the ’wire_fee_amortization’ factor, and further reduced if +deposit fees are below ’max_fee’). Default if missing is zero. + +@item wire_fee_amortization + +fees +maximum fee amortization +Over how many customer transactions does the merchant expect to +amortize wire fees on average? If the exchange’s wire fee is above +’max_wire_fee’, the difference is divided by this number to compute +the expected customer’s contribution to the wire fee. The customer’s +contribution may further be reduced by the difference between the +’max_fee’ and the sum of the actual deposit fees. Optional, default +value if missing is 1. 0 and negative values are invalid and also +interpreted as 1. + +@item pay_url + +pay_url +Which URL accepts payments. This is the URL where the wallet will +POST coins. + +@item fulfillment_url + +fulfillment URL +Which URL should the wallet go to for obtaining the fulfillment, for +example the HTML or PDF of an article that was bought, or an order +tracking system for shipments, or a simple human-readable Web page +indicating the status of the contract. + +@item order_id + +order ID +Alphanumeric identifier, freely definable by the merchant. Used by +the merchant to uniquely identify the transaction. + +@item summary + +summary +Short, human-readable summary of the contract. To be used when +displaying the contract in just one line, for example in the +transaction history of the customer. + +@item timestamp + +Time at which the offer was generated. + +@item pay_deadline + +payment deadline +Timestamp of the time by which the merchant wants the exchange to +definitively wire the money due from this contract. Once this +deadline expires, the exchange will aggregate all deposits where the +contracts are past the refund_deadline and execute one large wire +payment for them. Amounts will be rounded down to the wire transfer +unit; if the total amount is still below the wire transfer unit, it +will not be disbursed. + +@item refund_deadline + +refund deadline +Timestamp until which the merchant willing (and able) to give refunds +for the contract using Taler. Note that the Taler exchange will hold +the payment in escrow at least until this deadline. Until this time, +the merchant will be able to sign a message to trigger a refund to +the customer. After this time, it will no longer be possible to +refund the customer. Must be smaller than the pay_deadline. + +@item products + +product description +Array of products that are being sold to the customer. Each entry +contains a tuple with the following values: + + +@table @asis + +@item description + +Description of the product. + +@item quantity + +Quantity of the items to be shipped. May specify a unit (@code{1 kg}) +or just the count. + +@item price + +Price for quantity units of this product shipped to the given +delivery_location. Note that usually the sum of all of the prices +should add up to the total amount of the contract, but it may be +different due to discounts or because individual prices are +unavailable. + +@item product_id + +Unique ID of the product in the merchant’s catalog. Can generally +be chosen freely as it only has meaning for the merchant, but +should be a number in the range @math{[0@comma{}2^@{51@})}. + +@item taxes + +Map of applicable taxes to be paid by the merchant. The label is +the name of the tax, i.e. VAT, sales tax or income tax, and the +value is the applicable tax amount. Note that arbitrary labels are +permitted, as long as they are used to identify the applicable tax +regime. Details may be specified by the regulator. This is used to +declare to the customer which taxes the merchant intends to pay, +and can be used by the customer as a receipt. The information is +also likely to be used by tax audits of the merchant. + +@item delivery_date + +Time by which the product is to be delivered to the +delivery_location. + +@item delivery_location + +This should give a label in the locations map, specifying where +the item is to be delivered. +@end table + +Values can be omitted if they are not applicable. For example, if a +purchase is about a bundle of products that have no individual prices +or product IDs, the product_id or price may not be specified in the +contract. Similarly, for virtual products delivered directly via the +fulfillment URI, there is no delivery location. + +@item merchant + + +@table @asis + +@item address + +This should give a label in the locations map, specifying where +the merchant is located. + +@item name + +This should give a human-readable name for the merchant’s +business. + +@item jurisdiction + +This should give a label in the locations map, specifying the +jurisdiction under which this contract is to be arbitrated. +@end table + +@item locations + +location +Associative map of locations used in the contract. Labels for +locations in this map can be freely chosen and used whenever a +location is required in other parts of the contract. This way, if the +same location is required many times (such as the business address of +the customer or the merchant), it only needs to be listed (and +transmitted) once, and can otherwise be referred to via the label. A +non-exhaustive list of location attributes is the following: + + +@table @asis + +@item country + +Name of the country for delivery, as found on a postal package, +i.e. “France”. + +@item state + +Name of the state for delivery, as found on a postal package, i.e. +“NY”. + +@item region + +Name of the region for delivery, as found on a postal package. + +@item province + +Name of the province for delivery, as found on a postal package. + +@item city + +Name of the city for delivery, as found on a postal package. + +@item ZIP code + +ZIP code for delivery, as found on a postal package. + +@item street + +Street name for delivery, as found on a postal package. + +@item street number + +Street number (number of the house) for delivery, as found on a +postal package. +@end table + +name receiver name for delivery, either business or person name. + +Note that locations are not required to specify all of these fields, +and they is also allowed to have additional fields. Contract +renderers must render at least the fields listed above, and should +render fields that they do not understand as a key-value list. +@end table +@anchor{taler-merchant-api-tutorial The-Taler-Order-Format}@w{ } +@anchor{d}@w{ } +@anchor{b}@w{ } +@anchor{taler-merchant-api-tutorial Session_002dBound-Payments}@w{ } + +@c %**end of body +@bye diff --git a/texinfo/taler-merchant-figures/exchange-db.png b/texinfo/taler-merchant-figures/exchange-db.png Binary files differnew file mode 100644 index 00000000..421e5941 --- /dev/null +++ b/texinfo/taler-merchant-figures/exchange-db.png diff --git a/texinfo/taler-merchant.texi b/texinfo/taler-merchant.texi new file mode 100644 index 00000000..f1334973 --- /dev/null +++ b/texinfo/taler-merchant.texi @@ -0,0 +1,1461 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename taler-merchant.info +@documentencoding UTF-8 +@ifinfo +@*Generated by Sphinx 2.2.0.@* +@end ifinfo +@settitle Taler Merchant Manual +@defindex ge +@paragraphindent 0 +@exampleindent 4 +@finalout +@dircategory CATEGORY +@direntry +* MENU ENTRY: (taler-merchant.info). DESCRIPTION +@end direntry + +@definfoenclose strong,`,' +@definfoenclose emph,`,' +@c %**end of header + +@copying +@quotation +GNU Taler 0.6.0pre1, Sep 18, 2019 + +GNU Taler team + +Copyright @copyright{} 2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+) +@end quotation + +@end copying + +@titlepage +@title Taler Merchant Manual +@insertcopying +@end titlepage +@contents + +@c %** start of user preamble + +@c %** end of user preamble + +@ifnottex +@node Top +@top Taler Merchant Manual +@insertcopying +@end ifnottex + +@c %**start of body +@anchor{taler-merchant-manual doc}@anchor{0} +@menu +* Introduction:: +* Installation:: +* How to configure the merchant’s backend:: +* Testing:: +* Advanced topics:: + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* About GNU Taler:: +* About this manual:: +* Architecture overview:: + +Installation + +* Installing Taler using Docker:: +* Generic instructions:: +* Installing Taler on Debian GNU/Linux:: + +Generic instructions + +* Installation of dependencies:: +* Installing libgnunetutil:: +* Installing the GNU Taler exchange:: +* Installing the GNU Taler merchant backend:: + +How to configure the merchant’s backend + +* Backend options:: +* Sample backend configuration:: +* Launching the backend:: + +Advanced topics + +* Configuration format:: +* Using taler-config:: +* Merchant key management:: +* Using the SEPA wire transfer method:: +* Tipping visitors:: +* Generate payments:: + +Tipping visitors + +* Configure a reserve and exchange for tipping:: +* Fund the reserve:: +* Authorize a tip:: +* Picking up of the tip:: + +@end detailmenu +@end menu + +@node Introduction,Installation,Top,Top +@anchor{taler-merchant-manual gnu-taler-merchant-backend-operator-manual}@anchor{1}@anchor{taler-merchant-manual introduction}@anchor{2} +@chapter Introduction + + +@menu +* About GNU Taler:: +* About this manual:: +* Architecture overview:: + +@end menu + +@node About GNU Taler,About this manual,,Introduction +@anchor{taler-merchant-manual about-gnu-taler}@anchor{3} +@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). + +GNU Taler is not yet production-ready, after following this manual you +will have a backend that can process payments in “KUDOS”, but not +regular currencies. This is not so much because of limitations in the +backend, but because we are not aware of a Taler exchange operator +offering regular currencies today. + +@node About this manual,Architecture overview,About GNU Taler,Introduction +@anchor{taler-merchant-manual about-this-manual}@anchor{4}@anchor{taler-merchant-manual id1}@anchor{5} +@section About this manual + + +This tutorial targets system administrators who want to install a GNU +Taler merchant @emph{backend}. + +We expect some moderate familiarity with the compilation and +installation of free software packages. An understanding of cryptography +is not required. + +This first chapter of the tutorial will give a brief overview of the +overall Taler architecture, describing the environment in which the +Taler backend operates. The second chapter then explains how to install +the software, including key dependencies. The third chapter will explain +how to configure the backend, including in particular the configuration +of the bank account details of the merchant. + +The last chapter gives some additional information about advanced topics +which will be useful for system administrators but are not necessary for +operating a basic backend. + +@node Architecture overview,,About this manual,Introduction +@anchor{taler-merchant-manual architecture-overview}@anchor{6}@anchor{taler-merchant-manual id2}@anchor{7} +@section Architecture overview + + +crypto-currency +KUDOS +Taler is a pure payment system, not a new crypto-currency. As such, it +operates in a traditional banking context. In particular, this means +that in order to receive funds via Taler, the merchant must have a +regular bank account, and payments can be executed in ordinary +currencies such as USD or EUR. For testing purposes, Taler uses a +special currency “KUDOS” and includes its own special bank. + +The Taler software stack for a merchant consists of four main +components: + + +@itemize - + +@item +frontend +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 describes how to +integrate Taler with Web shop frontends. + +@item +back office +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 +backend +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 +DBMS +Postgres +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. +@end itemize + +The following image illustrates the various interactions of these key +components: + +@example +Missing diagram image +@end example + +RESTful +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,How to configure the merchant’s backend,Introduction,Top +@anchor{taler-merchant-manual installation}@anchor{8} +@chapter Installation + + +This chapter describes how to install the GNU Taler merchant backend. + +@menu +* Installing Taler using Docker:: +* Generic instructions:: +* Installing Taler on Debian GNU/Linux:: + +@end menu + +@node Installing Taler using Docker,Generic instructions,,Installation +@anchor{taler-merchant-manual installing-taler-using-docker}@anchor{9} +@section Installing Taler using Docker + + +This section provides instructions for the merchant backend installation +using ‘Docker‘. + +For security reasons, we run Docker against a VirtualBox instance, so +the @code{docker} command should connect to a @code{docker-machine} instance +that uses the VirtualBox driver. + +Therefore, the needed tools are: “docker“, “docker-machine“, and +“docker-compose“. Please refer to Docker’s official @footnote{@w{(1)} +@indicateurl{https://docs.docker.com/} +} documentation +in order to get those components installed, as that is not in this +manual’s scope. + +Before starting to build the merchant’s image, make sure a +“docker-machine“ instance is up and running. + +Because all of the Docker source file are kept in our “deployment“ +repository, we start by checking out the @code{git://taler.net/deployment} +codebase: + +@example +$ git clone git://taler.net/deployment +@end example + +Now we actually build the merchant’s image. From the same directory as +above: + +@example +$ cd deployment/docker/merchant/ +$ docker-compose build +@end example + +If everything worked as expected, the merchant is ready to be launched. +From the same directory as the previous step: + +@example +# Recall: the docker-machine should be up and running. +$ docker-compose up +@end example + +You should see some live logging from all the involved containers. At +this stage of development, you should also ignore some (harmless) error +message from postresql about already existing roles and databases. + +To test if everything worked as expected, it suffices to issue a simple +request to the merchant, as: + +@example +$ curl http://$(docker-machine ip)/ +# A greeting message should be returned by the merchant. +@end example + +@node Generic instructions,Installing Taler on Debian GNU/Linux,Installing Taler using Docker,Installation +@anchor{taler-merchant-manual generic-instructions}@anchor{a}@anchor{taler-merchant-manual id4}@anchor{b} +@section Generic instructions + + +This section provides generic instructions for the merchant backend +installation independent of any particular operating system. Operating +system specific instructions are provided in the following sections. 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. + +@menu +* Installation of dependencies:: +* Installing libgnunetutil:: +* Installing the GNU Taler exchange:: +* Installing the GNU Taler merchant backend:: + +@end menu + +@node Installation of dependencies,Installing libgnunetutil,,Generic instructions +@anchor{taler-merchant-manual id5}@anchor{c}@anchor{taler-merchant-manual installation-of-dependencies}@anchor{d} +@subsection Installation of dependencies + + +The following packages need to be installed before we can compile the +backend: + + +@itemize - + +@item +autoconf >= 2.69 + +@item +automake >= 1.14 + +@item +libtool >= 2.4 + +@item +autopoint >= 0.19 + +@item +libltdl >= 2.4 + +@item +libunistring >= 0.9.3 + +@item +libcurl >= 7.26 (or libgnurl >= 7.26) + +@item +GNU libmicrohttpd >= 0.9.39 + +@item +GNU libgcrypt >= 1.6 + +@item +libjansson >= 2.7 + +@item +Postgres >= 9.4, including libpq + +@item +libgnunetutil (from Git) + +@item +GNU Taler exchange (from Git) +@end itemize + +Except for the last two, these are available in most GNU/Linux +distributions and should just be installed using the respective package +manager. + +The following sections will provide detailed instructions for installing +the libgnunetutil and GNU Taler exchange dependencies. + +@node Installing libgnunetutil,Installing the GNU Taler exchange,Installation of dependencies,Generic instructions +@anchor{taler-merchant-manual id6}@anchor{e}@anchor{taler-merchant-manual installing-libgnunetutil}@anchor{f} +@subsection Installing libgnunetutil + + +GNUnet +Before you install libgnunetutil, you must download and install the +dependencies mentioned in the previous section, otherwise the build may +succeed but fail to export some of the tooling required by Taler. + +To download and install libgnunetutil, proceed as follows: + +@example +$ git clone https://gnunet.org/git/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}. + +@node Installing the GNU Taler exchange,Installing the GNU Taler merchant backend,Installing libgnunetutil,Generic instructions +@anchor{taler-merchant-manual id7}@anchor{10}@anchor{taler-merchant-manual installing-the-gnu-taler-exchange}@anchor{11} +@subsection Installing the GNU Taler exchange + + +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. + +@node Installing the GNU Taler merchant backend,,Installing the GNU Taler exchange,Generic instructions +@anchor{taler-merchant-manual id8}@anchor{12}@anchor{taler-merchant-manual installing-the-gnu-taler-merchant-backend}@anchor{13} +@subsection Installing the GNU Taler merchant backend + + +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. + +@node Installing Taler on Debian GNU/Linux,,Generic instructions,Installation +@anchor{taler-merchant-manual installing-taler-on-debian-gnu-002flinux}@anchor{14}@anchor{taler-merchant-manual installing-taler-on-debian-gnu-linux}@anchor{15} +@section Installing Taler on Debian GNU/Linux + + +Wheezy +Debian +Debian wheezy is too old and lacks most of the packages required. + +On Debian jessie, only GNU libmicrohttpd needs to be compiled from +source. To install dependencies on Debian jesse, run the following +commands: + +@example +# apt-get install \ + autoconf \ + automake \ + autopoint \ + libtool \ + libltdl-dev \ + libunistring-dev \ + libcurl4-gnutls-dev \ + libgcrypt20-dev \ + libjansson-dev \ + libpq-dev \ + postgresql-9.4 +# wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz +# wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz.sig +# gpg -v libmicrohttpd-latest.tar.gz # Should show signed by 939E6BE1E29FC3CC +# tar xf libmicrohttpd-latest.tar.gz +# cd libmicrohttpd-0* +# ./configure +# make install +@end example + +For more recent versions of Debian, you should instead run: + +@example +# apt-get install \ + autoconf \ + automake \ + autopoint \ + libtool \ + libltdl-dev \ + libunistring-dev \ + libcurl4-gnutls-dev \ + libgcrypt20-dev \ + libjansson-dev \ + libpq-dev \ + postgresql-9.5 \ + libmicrohttpd-dev +@end example + +For the rest of the installation, follow the generic installation +instructions starting with the installation of libgnunetutil. Note that +if you used the Debian wheezy instructions above, you need to pass +@code{--with-microhttpd=/usr/local/} to all @code{configure} invocations. + +@node How to configure the merchant’s backend,Testing,Installation,Top +@anchor{taler-merchant-manual how-to-configure-the-merchants-backend}@anchor{16} +@chapter How to configure the merchant’s backend + + +taler-config +taler.conf +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. The format of the configuration file is the well-known INI +file format. You can edit the file by hand, or use the @code{taler-config} +commands given as examples. For more information on @code{taler-config}, +see @ref{17,,Using taler-config}. + +@menu +* Backend options:: +* Sample backend configuration:: +* Launching the backend:: + +@end menu + +@node Backend options,Sample backend configuration,,How to configure the merchant’s backend +@anchor{taler-merchant-manual backend-options}@anchor{18}@anchor{taler-merchant-manual id9}@anchor{19} +@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: + +UNIX domain socket +TCP + +@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. + +port +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 + +currency +KUDOS + +@example +[TALER]/CURRENCY +@end example + +For testing purposes, the currency MUST match “KUDOS” so that tests +will work with the Taler demonstration exchange at +@indicateurl{https://exchange.demo.taler.net/}: + +@example +$ taler-config -s TALER -o CURRENCY -V KUDOS +@end example + +@item Database + +DBMS +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 + +Postgres +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 +$ sudu -u postgres createuser -d $USER +@end example + +as the Postgres database administrator (usually @code{postgres}) 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 + +exchange +To add an exchange to the list of trusted payment service providers, +you create a section with a name that starts with “exchange-”. In +that section, the following options need to be configured: + + +@itemize - + +@item +The “url” option specifies the exchange’s base URL. For example, +to use the Taler demonstrator use: + +@example +$ taler-config -s EXCHANGE-demo -o URL \ + -V https://exchange.demo.taler.net/ +@end example + +@item +master key +The “master_key” option specifies the exchange’s master public key +in base32 encoding. For the Taler demonstrator, use: + +@example +$ taler-config -s 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 + +@item Instances + +instance +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 accounts and key for signing contracts. It is +mandatory to configure a "default" instance. + + +@itemize - + +@item +The “KEYFILE” option specifies the file containing the instance’s +private signing key. For example, use: + +@example +$ taler-config -s INSTANCE-default -o KEYFILE \ + -V '$@{TALER_CONFIG_HOME@}/merchant/instace/default.key' +@end example + +@item +The “NAME” option specifies a human-readable name for the +instance. For example, use: + +@example +$ taler-config -s INSTANCE-default -o NAME \ + -V 'Kudos Inc.' +@end example + +@item +The optional “TIP_EXCHANGE” and “TIP_EXCHANGE_PRIV_FILENAME” +options are discussed in Tipping visitors +@end itemize + +@item Accounts + +wire format +In order to receive payments, the merchant backend needs to +communicate bank account details to the exchange. For this, the +configuration must include one or more sections named “ACCOUNT-name” +where @code{name} can be replaced by some human-readable word +identifying the account. For each section, the following options +should be provided: + + +@itemize - + +@item +The “URL” option specifies a @code{payto://}-URL for the account of +the merchant. For example, use: + +@example +$ taler-config -s ACCOUNT-bank -o NAME \ + -V 'payto://x-taler-bank/bank.demo.taler.net/4' +@end example + +@item +The “WIRE_RESPONSE” option specifies where Taler should store the +(salted) JSON encoding of the wire account. The file given will be +created if it does not exist. For example, use: + +@example +$ taler-config -s ACCOUNT-bank -o WIRE_RESPONSE \ + -V '@{$TALER_CONFIG_HOME@}/merchant/bank.json' +@end example + +@item +The “PLUGIN” option specifies which wire plugin should be used for +this account. The plugin must support the wire method used by the +URL. For example, use: + +@example +$ taler-config -s ACCOUNT-bank -o PLUGIN \ + -V taler_bank +@end example + +@item +For each @code{instance} that should use this account, you should set +@code{HONOR_instance} and @code{ACTIVE_instance} to YES. The first +option will cause the instance to accept payments to the account +(for existing contracts), while the second will cause the backend +to include the account as a possible option for new contracts. + +For example, use: + +@example +$ taler-config -s ACCOUNT-bank -o HONOR_default \ + -V YES +$ taler-config -s ACCOUNT-bank -o ACTIVE_default \ + -V YES +@end example + +to use “account-bank” for the “default” instance. +@end itemize + +Depending on which PLUGIN you configured, you may additionally +specfiy authentication options to enable the plugin to use the +account. + +For example, with @code{taler_bank} plugin, use: + +@example +$ taler-config -s ACCOUNT-bank -o TALER_BANK_AUTH_METHOD \ + -V basic +$ taler-config -s ACCOUNT-bank -o USERNAME \ + -V user42 +$ taler-config -s ACCOUNT-bank -o PASSWORD \ + -V pass42 +@end example + +Note that additional instances can be specified using different +tokens in the section name instead of @code{default}. +@end table + +@node Sample backend configuration,Launching the backend,Backend options,How to configure the merchant’s backend +@anchor{taler-merchant-manual id10}@anchor{1a}@anchor{taler-merchant-manual sample-backend-configuration}@anchor{1b} +@section Sample backend configuration + + +configuration +The following is an example for a complete backend configuration: + +@example +[TALER] +CURRENCY = KUDOS + +[MERCHANT] +SERVE = TCP +PORT = 8888 +DATABASE = postgres + +[MERCHANTDB-postgres] +CONFIG = postgres:///donations + +[INSTANCE-default] +KEYFILE = $DATADIR/key.priv +NAME = "Kudos Inc." + +[ACCOUNT-bank] +URL = payto://x-taler-bank/bank.demo.taler.net/4 +WIRE_RESPONSE = $DATADIR/bank.json +PLUGIN = taler_bank +HONOR_default = YES +ACTIVE_default = YES +TALER_BANK_AUTH_METHOD = basic +USERNAME = my_user +PASSWORD = 1234pass + +[EXCHANGE-trusted] +URL = https://exchange.demo.taler.net/ +MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 +CURRENCY = KUDOS +@end example + +Given the above configuration, the backend will use a database named +@code{donations} within Postgres. + +The backend will deposit the coins it receives to the exchange at +@indicateurl{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. + +@node Launching the backend,,Sample backend configuration,How to configure the merchant’s backend +@anchor{taler-merchant-manual id11}@anchor{1c}@anchor{taler-merchant-manual launching-the-backend}@anchor{1d} +@section Launching the backend + + +backend +taler-merchant-httpd +Assuming you have configured everything correctly, you can launch the +merchant backend using: + +@example +$ taler-merchant-httpd +@end example + +When launched for the first time, this command will print a message +about generating your private key. If everything worked as expected, the +command + +@example +$ curl http://localhost:8888/ +@end example + +should return the message + +@example +Hello, I'm a merchant's Taler backend. This HTTP server is not for humans. +@end example + +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 Testing,Advanced topics,How to configure the merchant’s backend,Top +@anchor{taler-merchant-manual id12}@anchor{1e}@anchor{taler-merchant-manual testing}@anchor{1f} +@chapter Testing + + +The tool @code{taler-merchant-generate-payments} can be used to test the +merchant backend installation. It implements all the payment’s steps in +a programmatically way, relying on the backend you give it as input. +Note that this tool gets installed along all the merchant backend’s +binaries. + +This tool gets configured by a config file, that must have the following +layout: + +@example +[PAYMENTS-GENERATOR] + +# The exchange used during the test: make sure the merchant backend +# being tested accpets this exchange. +# If the sysadmin wants, she can also install a local exchange +# and test against it. +EXCHANGE = https://exchange.demo.taler.net/ + +# This value must indicate some URL where the backend +# to be tested is listening; it doesn't have to be the +# "official" one, though. +MERCHANT = http://localbackend/ + +# This value is used when the tool tries to withdraw coins, +# and must match the bank used by the exchange. If the test is +# done against the exchange at https://exchange.demo.taler.net/, +# then this value can be "https://bank.demo.taler.net/". +BANK = https://bank.demo.taler.net/ + +# The merchant instance in charge of serving the payment. +# Make sure this instance has a bank account at the same bank +# indicated by the 'bank' option above. +INSTANCE = default + +# The currency used during the test. Must match the one used +# by merchant backend and exchange. +CURRENCY = KUDOS +@end example + +Run the test in the following way: + +@example +$ taler-merchant-generate-payments [-c config] [-e EURL] [-m MURL] +@end example + +The argument @code{config} given to @code{-c} points to the configuration file +and is optional – @code{~/.config/taler.conf} will be checked by default. +By default, the tool forks two processes: one for the merchant backend, +and one for the exchange. The option @code{-e} (@code{-m}) avoids any exchange +(merchant backend) fork, and just runs the generator against the +exchange (merchant backend) running at @code{EURL} (@code{MURL}). + +Please NOTE that the generator contains @emph{hardcoded} values, as for +deposit fees of the coins it uses. In order to work against the used +exchange, those values MUST match the ones used by the exchange. + +The following example shows how the generator "sets" a deposit fee of +EUR:0.01 for the 5 EURO coin. + +@example +// from <merchant_repository>/src/sample/generate_payments.c +@{ .oc = OC_PAY, + .label = "deposit-simple", + .expected_response_code = MHD_HTTP_OK, + .details.pay.contract_ref = "create-proposal-1", + .details.pay.coin_ref = "withdraw-coin-1", + .details.pay.amount_with_fee = concat_amount (currency, "5"), + .details.pay.amount_without_fee = concat_amount (currency, "4.99") @}, +@end example + +The logic calculates the deposit fee according to the subtraction: +@code{amount_with_fee - amount_without_fee}. + +The following example shows a 5 EURO coin configuration - needed by the +used exchange - which is compatible with the hardcoded example above. + +@example +[COIN_eur_5] +value = EUR:5 +duration_overlap = 5 minutes +duration_withdraw = 7 days +duration_spend = 2 years +duration_legal = 3 years +fee_withdraw = EUR:0.00 +fee_deposit = EUR:0.01 # important bit +fee_refresh = EUR:0.00 +fee_refund = EUR:0.00 +rsa_keysize = 1024 +@end example + +If the command terminates with no errors, then the merchant backend is +correctly installed. + +After this operation is done, the merchant database will have some dummy +data in it, so it may be convenient to clean all the tables; to this +purpose, issue the following command: + +@example +$ taler-merchant-dbinit -r +@end example + +@node Advanced topics,,Testing,Top +@anchor{taler-merchant-manual advanced-topics}@anchor{20} +@chapter Advanced topics + + +@menu +* Configuration format:: +* Using taler-config:: +* Merchant key management:: +* Using the SEPA wire transfer method:: +* Tipping visitors:: +* Generate payments:: + +@end menu + +@node Configuration format,Using taler-config,,Advanced topics +@anchor{taler-merchant-manual configuration-format}@anchor{21} +@section Configuration format + + +configuration +In Taler realm, any component obeys to the same pattern to get +configuration values. According to this pattern, once the component has +been installed, the installation deploys default values in +$@{prefix@}/share/taler/config.d/, in .conf files. In order to override +these defaults, the user can write a custom .conf file and either pass +it to the component at execution time, or name it taler.conf and place +it under $HOME/.config/. + +A config file is a text file containing sections, and each section +contains its values. The right format follows: + +@example +[section1] +value1 = string +value2 = 23 + +[section2] +value21 = string +value22 = /path22 +@end example + +Throughout any configuration file, it is possible to use @code{$}-prefixed +variables, like @code{$VAR}, especially when they represent filesystem +paths. It is also possible to provide defaults values for those +variables that are unset, by using the following syntax: +@code{$@{VAR:-default@}}. However, there are two ways a user can set +@code{$}-prefixable variables: + +by defining them under a @code{[paths]} section, see example below, + +@example +[paths] +TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data +.. +[section-x] +path-x = $@{TALER_DEPLOYMENT_SHARED@}/x +@end example + +or by setting them in the environment: + +@example +$ export VAR=/x +@end example + +The configuration loader will give precedence to variables set under +@code{[path]}, though. + +The utility @code{taler-config}, which gets installed along with the +exchange, serves to get and set configuration values without directly +editing the .conf. The option @code{-f} is particularly useful to resolve +pathnames, when they use several levels of @code{$}-expanded variables. See +@code{taler-config --help}. + +Note that, in this stage of development, the file +@code{$HOME/.config/taler.conf} can contain sections for @emph{all} the +component. For example, both an exchange and a bank can read values from +it. + +The repository @code{git://taler.net/deployment} contains examples of +configuration file used in our demos. See under @code{deployment/config}. + +@quotation + +@strong{Note} + +Expectably, some components will not work just by using default +values, as their work is often interdependent. For example, a +merchant needs to know an exchange URL, or a database name. +@end quotation + +@node Using taler-config,Merchant key management,Configuration format,Advanced topics +@anchor{taler-merchant-manual using-taler-002dconfig}@anchor{22}@anchor{taler-merchant-manual using-taler-config}@anchor{23} +@section Using taler-config + + +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 ACCOUNT-bank \ + -o WIRE_RESPONSE +$ taler-config -f -s ACCOUNT-bank \ + -o WIRE_RESPONSE +@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. + +@node Merchant key management,Using the SEPA wire transfer method,Using taler-config,Advanced topics +@anchor{taler-merchant-manual id13}@anchor{24}@anchor{taler-merchant-manual merchant-key-management}@anchor{25} +@section Merchant key management + + +merchant key +KEYFILE +The option “KEYFILE” in the section “INSTANCE-default” specifies the +path to the instance’s private key. You do not need to create a key +manually, the backend will generate it automatically if it is missing. +While generally unnecessary, it is possible to display the corresponding +public key using the @code{gnunet-ecc} command-line tool: + +@example +$ gnunet-ecc -p \ + $(taler-config -f -s INSTANCE-default \ + -o KEYFILE) +@end example + +@node Using the SEPA wire transfer method,Tipping visitors,Merchant key management,Advanced topics +@anchor{taler-merchant-manual sepa-configuration}@anchor{26}@anchor{taler-merchant-manual using-the-sepa-wire-transfer-method}@anchor{27} +@section Using the SEPA wire transfer method + + +SEPA +EBICS +The following is a sample configuration for the SEPA wire transfer +method: @footnote{@w{(2)} +Supporting SEPA is still work in progress; the backend will accept +this configuration, but the exchange will not work with SEPA today. +}. + +Then, to configure the EBICS backend for SEPA payments in EUR, the +following configuration options need to be set: + +@example +$ taler-config -s TALER -o CURRENCY -V EUR +$ taler-config -s ACCOUNT-e -o PLUGIN -V ebics +$ taler-config -s ACCOUNT-e -o URL \ + -V payto://sepa/XY00111122223333444455556666 +$ taler-config -s ACCOUNT-e -o WIRE_RESPONSE + -V '$@{DATADIR@}/b.json' +@end example + +Please note that you will also have to configure an exchange and/or +auditors that support SEPA. However, we cannot explain how to do this +yet as such entities do not yet exist. Once such entities do exist, we +expect future versions of the Taler backend to ship with pre-configured +exchanges and auditors for common denominations. + +@node Tipping visitors,Generate payments,Using the SEPA wire transfer method,Advanced topics +@anchor{taler-merchant-manual id15}@anchor{28}@anchor{taler-merchant-manual tipping-visitors}@anchor{29} +@section Tipping visitors + + +tipping +Taler can also be used to tip Web site visitors. For example, you may be +running an online survey, and you want to reward those people that have +dutifully completed the survey. If they have installed a Taler wallet, +you can provide them with a tip for their deeds. This section describes +how to setup the Taler merchant backend for tipping. + +There are four basic steps that must happen to tip a visitor. + +@menu +* Configure a reserve and exchange for tipping:: +* Fund the reserve:: +* Authorize a tip:: +* Picking up of the tip:: + +@end menu + +@node Configure a reserve and exchange for tipping,Fund the reserve,,Tipping visitors +@anchor{taler-merchant-manual configure-a-reserve-and-exchange-for-tipping}@anchor{2a}@anchor{taler-merchant-manual id16}@anchor{2b} +@subsection Configure a reserve and exchange for tipping + + +gnunet-ecc +reserve key +To tip users, you first need to create a reserve. A reserve is a pool of +money held in escrow at the Taler exchange. This is the source of the +funds for the tips. Tipping will fail (resulting in disappointed +visitors) if you do not have enough funds in your reserve! + +First, we configure the backend. You need to enable tipping for each +instance separately, or you can use an instance only for tipping. To +configure the “default” instance for tipping, use the following +configuration: + +@example +[INSTANCE-default] +# this is NOT the tip.priv +KEYFILE = signing_key.priv +# replace the URL with the URL of the exchange you will use +TIP_EXCHANGE = https://exchange:443/ +# here put the path to the file created with "gnunet-ecc -g1 tip.priv" +TIP_RESERVE_PRIV_FILENAME = tip.priv +@end example + +Note that the KEYFILE option should have already been present for the +instance. It has nothing to do with the “tip.priv” file we created +above, and you should probably use a different file here. + +Instead of manually editing the configuration, you could also run: + +@example +$ taler-config -s INSTANCE-default \ + -o TIP_RESERVE_PRIV_FILENAME \ + -V tip.priv +$ taler-config -s INSTANCE-default \ + -o TIP_EXCHANGE \ + -V https://exchange:443/ +@end example + +Next, to create the @code{TIP_RESERVE_PRIV_FILENAME} file, use: + +@example +$ gnunet-ecc -g 1 \ + $(taler-config -f -s INSTANCE-default \ + -o TIP-RESERVE_PRIV_FILENAME) +@end example + +This will create a file with the private key that will be used to +identify the reserve. You need to do this once for each instance that is +configured to tip. + +Now you can (re)start the backend with the new configuration. + +@node Fund the reserve,Authorize a tip,Configure a reserve and exchange for tipping,Tipping visitors +@anchor{taler-merchant-manual fund-the-reserve}@anchor{2c}@anchor{taler-merchant-manual id17}@anchor{2d} +@subsection Fund the reserve + + +reserve +close +To fund the reserve, you must first extract the public key from +“tip.priv”: + +@example +$ gnunet-ecc --print-public-key \ + $(taler-config -f -s INSTANCE-default \ + -o TIP-RESERVE_PRIV_FILENAME) +@end example + +In our example, the output for the public key is: + +@example +QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG +@end example + +You now need to make a wire transfer to the exchange’s bank account +using the public key as the wire transfer subject. The exchange’s bank +account details can be found in JSON format at +“@indicateurl{https://exchange:443//wire/METHOD}” where METHOD is the respective wire +method (i.e. “sepa”). Depending on the exchange’s operator, you may also +be able to find the bank details in a human-readable format on the main +page of the exchange. + +Make your wire transfer and (optionally) check at +“@indicateurl{https://exchange:443/reserve/status/reserve_pub=QPE24X}...” whether your +transfer has arrived at the exchange. + +Once the funds have arrived, you can start to use the reserve for +tipping. + +Note that an exchange will typically close a reserve after four weeks, +wiring all remaining funds back to the sender’s account. Thus, you +should plan to wire funds corresponding to a campaign of about two weeks +to the exchange initially. If your campaign runs longer, you should wire +further funds to the reserve every other week to prevent it from +expiring. + +@node Authorize a tip,Picking up of the tip,Fund the reserve,Tipping visitors +@anchor{taler-merchant-manual authorize-a-tip}@anchor{2e}@anchor{taler-merchant-manual id18}@anchor{2f} +@subsection Authorize a tip + + +When your frontend has reached the point where a client is supposed to +receive a tip, it needs to first authorize the tip. For this, the +frontend must use the “/tip-authorize” API of the backend. To authorize +a tip, the frontend has to provide the following information in the body +of the POST request: + + +@itemize - + +@item +The amount of the tip + +@item +The justification (only used internally for the back-office) + +@item +The URL where the wallet should navigate next after the tip was +processed + +@item +The tip-pickup URL (see next section) +@end itemize + +In response to this request, the backend will return a tip token, an +expiration time and the exchange URL. The expiration time will indicate +how long the tip is valid (when the reserve expires). The tip token is +an opaque string that contains all the information needed by the wallet +to process the tip. The frontend must send this tip token to the browser +in a special “402 Payment Required” response inside the @code{X-Taler-Tip} +header. + +The frontend should handle errors returned by the backend, such as +missconfigured instances or a lack of remaining funds for tipping. + +@node Picking up of the tip,,Authorize a tip,Tipping visitors +@anchor{taler-merchant-manual id19}@anchor{30}@anchor{taler-merchant-manual picking-up-of-the-tip}@anchor{31} +@subsection Picking up of the tip + + +The wallet will POST a JSON object to the shop’s “/tip-pickup” handler. +The frontend must then forward this request to the backend. The response +generated by the backend can then be forwarded directly to the wallet. + +@node Generate payments,,Tipping visitors,Advanced topics +@anchor{taler-merchant-manual generate-payments}@anchor{32}@anchor{taler-merchant-manual id20}@anchor{33} +@section Generate payments + + +testing database +The merchant codebase offers the @code{taler-merchant-benchmark} tool to +populate the database with fake payments. This tool is in charge of +starting a merchant, exchange, and bank processes, and provide them all +the input to accomplish payments. Note that each component will use its +own configuration (as they would do in production). + +The tool takes all of the values it needs from the command line, with +some of them being mandatory. Among those, we have: + + +@itemize - + +@item +@code{--currency=K} Use currency @emph{K}, for example to craft coins to +withdraw. + +@item +@code{--bank-url=URL} Assume that the bank is serving under the base URL +@emph{URL}. This option is only actually used by the tool to check if the +bank was well launched. + +@item +@code{--merchant-url=URL} Reach the merchant through @emph{URL}, for +downloading contracts and sending payments. +@end itemize + +The tool then comes with two operation modes: @emph{ordinary}, and @emph{corner}. +The first just executes normal payments, meaning that it uses the +default instance and make sure that all payments get aggregated. The +second gives the chance to leave some payments unaggregated, and also to +use merchant instances other than the default (which is, actually, the +one used by default by the tool). + +Note: the abilty of driving the aggregation policy is useful for testing +the backoffice facility. + +Any subcommand is also equipped with the canonical @code{--help} option, so +feel free to issue the following command in order to explore all the +possibilities. For example: + +@example +$ taler-merchant-benchmark corner --help +@end example + +will show all the options offered by the @emph{corner} mode. Among the most +interesting, there are: + + +@itemize - + +@item +@code{--two-coins=TC} This option instructs the tool to perform @emph{TC} +many payments that use two coins, because normally only one coin is +spent per payment. + +@item +@code{--unaggregated-number=UN} This option instructs the tool to +perform @emph{UN} (one coin) payments that will be left unaggregated. + +@item +@code{--alt-instance=AI} This option instructs the tool to perform +payments using the merchant instance @emph{AI} (instead of the @emph{default} +instance) +@end itemize + +As for the @code{ordinary} subcommand, it is worth explaining the following +options: + + +@itemize - + +@item +@code{--payments-number=PN} Instructs the tool to perform @emph{PN} payments. + +@item +@code{--tracks-number=TN} Instructs the tool to perform @emph{TN} tracking +operations. Note that the @strong{total} amount of operations will be two +times @emph{TN}, since "one" tracking operation accounts for +@code{/track/transaction} and @code{/track/transfer}. This command should +only be used to see if the operation ends without problems, as no +actual measurement of performance is provided (despite of the +’benchmark’ work used in the tool’s name). +@end itemize +@anchor{17}@w{ } +@anchor{taler-merchant-manual Using-taler_002dconfig}@w{ } + +@c %**end of body +@bye |